rtcc.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015, Zolertia <http://www.zolertia.com>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the Institute nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * This file is part of the Contiki operating system.
 *
 */
/* -------------------------------------------------------------------------- */
/**
 * \addtogroup zoul
 * @{
 *
 * \defgroup remote-rtcc RE-Mote Real Time Clock Calendar
 *
 * Driver for the RE-Mote on-board ultra-low power RTCC (Real Time Clock
 * Calendar)
 * @{
 *
 * \file
 * Header file for the RE-Mote RF antenna switch
 */
/* -------------------------------------------------------------------------- */
#ifndef RTCC_H_
#define RTCC_H_
/* -------------------------------------------------------------------------- */
#include <stdio.h>
#include "i2c.h"
/* -------------------------------------------------------------------------- */
/**
 * \name Callback function to handle the RTCC alarm interrupt and macro
 * @{
 */
#define RTCC_REGISTER_INT1(ptr) rtcc_int1_callback = ptr;
extern void (*rtcc_int1_callback)(uint8_t value);
/** @} */
/* -------------------------------------------------------------------------- */
/** \name AB08XX Address registers
 * @{
 */
/* -------------------------------------------------------------------------- */
/* Time/date registers (no offset) */
#define CENTHS_ADDR            0x00
#define SEC_ADDR               0x01
#define MIN_ADDR               0x02
#define HOUR_ADDR              0x03
#define DAY_ADDR               0x04
#define MONTHS_ADDR            0x05
#define YEAR_ADDR              0x06
#define WEEKDAYLS_ADDR         0x07

/* Alarm registers */
#define ALARM_MAP_OFFSET       0x08
#define HUNDREDTHS_ALARM_ADDR  0x00
#define SECONDS_ALARM_ADDR     0x01
#define MINUTES_ALARM_ADDR     0x02
#define HOURS_ALARM_ADDR       0x03
#define DAY_ALARMS_ADDR        0x04
#define MONTHS_ALARM_ADDR      0x05
#define WEEKDAYS_ALARM_ADDR    0x06

/* Configuration registers */
#define CONFIG_MAP_OFFSET      0x0F
#define STATUS_ADDR            0x00
#define CTRL_1_ADDR            0x01
#define CTRL_2_ADDR            0x02
#define INT_MASK_ADDR          0x03
#define SQW_ADDR               0x04
#define CAL_XT_ADDR            0x05
#define CAL_RC_HI_ADDR         0x06
#define CAL_RC_LO_ADDR         0x07
#define INT_POL_ADDR           0x08
#define TIMER_CONTROL_ADDR     0x09
#define TIMER_COUNTDOWN_ADDR   0x0A
#define TIMER_INITIAL_ADDR     0x0B
#define WDT_ADDR               0x0C
#define OSC_CONTROL_ADDR       0x0D
#define OSC_STATUS_ADDR        0x0E
#define CONF_KEY_ADDR          0x10
#define TRICKLE_ADDR           0x11
#define BREF_CTRL_ADDR         0x12
#define AF_CTRL_ADDR           0x17
#define BAT_MODE_IO_ADDR       0x18
#define ASTAT_ADDR             0x20
#define OCTRL_ADDR             0x21
#define EXT_ADDR               0x30
/* 256b. The upper 2 bits are taken from XADS field */
#define RAM_1_ADDR             (CONFIG_MAP_OFFSET + 0x31)
/* 256b. The upper 2 bits are taken from XADA field */
#define RAM_2_ADDR             (CONFIG_MAP_OFFSET + 0x71)
/** @} */
/* -------------------------------------------------------------------------- */
/** \name RTCC Bitmasks and shifts
 * @{
 */
#define STATUS_CB              0x80
#define STATUS_BAT             0x40
#define STATUS_WDT             0x20
#define STATUS_BL              0x10
#define STATUS_TIM             0x08
#define STATUS_ALM             0x04
#define STATUS_EX2             0x02
#define STATUS_EX1             0x01

#define CTRL1_WRTC             0x01
#define CTRL1_ARST             0x04
#define CTRL1_OUT              0x10
#define CTRL1_OUTB             0x20
#define CTRL1_1224             0x40
#define CTRL1_STOP             0x80

/* Defines the nIRQ pin control */
#define CTRL2_OUT1S_NIRQ_OUT        0x00
#define CTRL2_OUT1S_NIRQ_SQW_OUT    0x01
#define CTRL2_OUT1S_NIRQ_SQW_NIRQ   0x02
#define CTRL2_OUT1S_NIRQ_NAIRQ_OUT  0x03

/* Defines the nIRQ2 pin control */
#define CTRL2_OUT2S_SQW_OUT         0x04
#define CTRL2_OUT2S_NAIRQ_OUTB      0x0C
#define CTRL2_OUT2S_TIRQ_OUTB       0x10
#define CTRL2_OUT2S_NTIRQ_OUTB      0x14
#define CTRL2_OUT2S_OUTB            0x1C

/* Interrupt Mask */
#define INTMASK_EX1E                0x01
#define INTMASK_EX2E                0x02
#define INTMASK_AIE                 0x04
#define INTMASK_TIE                 0x08
#define INTMASK_BLIE                0x10
#define INTMASK_IM_HIGH             0x20
#define INTMASK_IM_MED              0x40
#define INTMASK_IM_LOW              0x60
#define INTMASK_CEB                 0x80

/* Timer countdown control */
#define COUNTDOWN_TIMER_TE          0x80
#define COUNTDOWN_TIMER_TM          0x40
#define COUNTDOWN_TIMER_TRPT        0x20
#define COUNTDOWN_TIMER_RPT_SECOND  0x1C
#define COUNTDOWN_TIMER_RPT_MINUTE  0x18
#define COUNTDOWN_TIMER_RPT_HOUR    0x24
#define COUNTDOWN_TIMER_RPT_DAY     0x10
#define COUNTDOWN_TIMER_RPT_WEEK    0x0C
#define COUNTDOWN_TIMER_RPT_MONTH   0x08
#define COUNTDOWN_TIMER_RPT_YEAR    0x04
#define COUNTDOWN_TIMER_RPT_SHIFT   0x02
#define COUNTDOWN_TIMER_TFS_ONE     0x01
#define COUNTDOWN_TIMER_TFS_TWO     0x02
#define COUNTDOWN_TIMER_TFS_THREE   0x03

/* Oscillator control */
#define OSCONTROL_ACIE              0x01
#define OSCONTROL_OFIE              0x02
#define OSCONTROL_FOS               0x08
#define OSCONTROL_AOS               0x10
#define OSCONTROL_ACAL_NO_CAL       0x00
#define OSCONTROL_ACAL_17_MIN       0x40
#define OSCONTROL_ACAL_9_MIN        0x60
#define OSCONTROL_OSEL              0x80

/** @} */
/* -------------------------------------------------------------------------- */
/** \name RTCC operational values
 * @{
 */
/* I2C address (7-bits) */
#define AB08XX_ADDR                0x69
#define INT_BUFF_SIZE              20L
#define TCS_DIODE_3K               (TCS_ENABLE + 0x05)
#define TCS_DIODE_6K               (TCS_ENABLE + 0x06)
#define TCS_DIODE_11K              (TCS_ENABLE + 0x07)
#define RTCC_TOGGLE_PM_BIT         0x20
#define RTCC_FIX_10THS_HUNDRETHS   0xF0
#define RTCC_FIX_100THS_HUNDRETHS  0xFF
#define RTCC_TD_MAP_SIZE           (WEEKDAYLS_ADDR + 1)
#define RTCC_ALARM_MAP_SIZE        (WEEKDAYS_ALARM_ADDR + 1)
#define RTCC_CONFIG_MAP_SIZE       (BREF_CTRL_ADDR + 1)
/** @} */
/* -------------------------------------------------------------------------- */
/** \name RTCC error values
 * @{
 */
#define AB08_ERROR                 (-1)
#define AB08_SUCCESS               0x00
/** @} */
/* -------------------------------------------------------------------------- */
/** \name RTCC enumeration and options
 * @{
 */
enum {
  RTCC_PRINT_DATE = 0,
  RTCC_PRINT_CONFIG,
  RTCC_PRINT_ALARM,
  RTCC_PRINT_ALARM_DEC,
  RTCC_PRINT_DATE_DEC,
  RTCC_PRINT_MAX,
};
/* -------------------------------------------------------------------------- */
enum {
  RTCC_ALARM_OFF = 0,
  RTCC_ALARM_ON,
  RTCC_ALARM_MAX,
};
/* -------------------------------------------------------------------------- */
enum {
  RTCC_CMD_UNLOCK = 0,
  RTCC_CMD_LOCK,
  RTCC_CMD_ENABLE,
  RTCC_CMD_STOP,
  RTCC_CMD_MAX,
};
/* -------------------------------------------------------------------------- */
enum {
  RTCC_24H_MODE = 0,
  RTCC_12H_MODE_AM,
  RTCC_12H_MODE_PM,
};
/* -------------------------------------------------------------------------- */
enum {
  RTCC_CENTURY_19XX_21XX = 1,
  RTCC_CENTURY_20XX,
};
/* -------------------------------------------------------------------------- */
enum {
  RTCC_REPEAT_NONE = 0,
  RTCC_REPEAT_YEAR,
  RTCC_REPEAT_MONTH,
  RTCC_REPEAT_WEEK,
  RTCC_REPEAT_DAY,
  RTCC_REPEAT_HOUR,
  RTCC_REPEAT_MINUTE,
  RTCC_REPEAT_SECOND,
  RTCC_REPEAT_10THS,
  RTCC_REPEAT_100THS,
};
/* -------------------------------------------------------------------------- */
enum {
  RTCC_CONFKEY_OSCONTROL = 0xA1,
  RTCC_CONFKEY_SWRESET   = 0x3C,
  RTCC_CONFKEY_DEFREGS   = 0x9D,
};
/* -------------------------------------------------------------------------- */
enum {
  RTCC_CAL_XT_OSC = 0,
  RTCC_CAL_RC_OSC,
};
/* -------------------------------------------------------------------------- */
enum {
  RTCC_AUTOCAL_DISABLE = 0,
  RTCC_AUTOCAL_ONCE,
  RTCC_AUTOCAL_17_MIN,
  RTCC_AUTOCAL_9_MIN,
};
/* -------------------------------------------------------------------------- */
enum {
  RTCC_TRIGGER_INT1 = 0,
  RTCC_TRIGGER_INT2,
  RTCC_TRIGGER_BOTH,
};

/** @} */
/* -------------------------------------------------------------------------- */
/** \name Readable Date and time memory map implementation
 *
 * This simplified structure allows the user to set date/alarms with a
 * reduced structure, without the bit-defined restrictions of the memory map,
 * using decimal values
 *
 * @{
 */
typedef struct ab0805_struct_simple_td_reg {
  uint8_t miliseconds;
  uint8_t seconds;
  uint8_t minutes;
  uint8_t hours;
  uint8_t day;
  uint8_t months;
  uint8_t years;
  uint8_t weekdays;
  uint8_t mode;
  uint8_t century;
}  __attribute__ ((packed)) simple_td_map;
/** @} */
/* -------------------------------------------------------------------------- */
/**
 * \name RTCC User functions
 * @{
 */

/**
 * \brief Set the time and date
 * \param *data Time and date value (decimal format)
 * \return
 * \           AB08_SUCCESS date/time set
 * \           AB08_ERROR failed to set time/date (enable DEBUG for more info)
 */
int8_t rtcc_set_time_date(simple_td_map *data);

/**
 * \brief Get the current time and date
 * \param *data buffer to store the results
 * \return
 * \           AB08_SUCCESS date/time set
 * \           AB08_ERROR failed to set time/date (enable DEBUG for more info)
 */
int8_t rtcc_get_time_date(simple_td_map *data);

/**
 * \brief Print data from the RTCC module, either from the memory
 *        map (values in BCD) or actual readable data (decimal).
 * \param value value to print, see RTCC_PRINT_* options available
 * \return
 * \           AB08_SUCCESS date/time set
 * \           AB08_ERROR failed to set time/date (enable DEBUG for more info)
 */
int8_t rtcc_print(uint8_t value);

/**
 * \brief Configure the RTCC to match an alarm counter
 * \param data date and time values (in decimal) to match against
 * \param state set on/off the alarm interruption
 * \param repeat set the frequency of the alarm (minute, hourly, daily, etc.)
 * \param trigger interrupt trigger (INT1, INT2 or both)
 * \return
 * \           AB08_SUCCESS date/time set
 * \           AB08_ERROR failed to set time/date (enable DEBUG for more info)
 */
int8_t rtcc_set_alarm_time_date(simple_td_map *data, uint8_t state,
                                uint8_t repeat, uint8_t trigger);

/**
 * \brief Increments the current date by a number of seconds
 * \param data structure to store the date
 * \param seconds the numberof seconds to increment the date
 * \return
 * \           AB08_SUCCESS updated date values
 * \           AB08_ERROR failed to return the values
 */
int8_t rtcc_date_increment_seconds(simple_td_map *data, uint16_t seconds);

/**
 * \brief Manually calibrate the RTCC
 * \param mode oscillator to calibrate
 * \param adjust value (in ppm) to adjust the oscillator
 * \return
 * \           AB08_SUCCESS date/time set
 * \           AB08_ERROR failed to set time/date (enable DEBUG for more info)
 */
int8_t rtcc_set_calibration(uint8_t mode, int32_t adjust);

/**
 * \brief Set the autocallibration period
 * \param period autocalibration configuration
 * \return
 * \           AB08_SUCCESS date/time set
 * \           AB08_ERROR failed to set time/date (enable DEBUG for more info)
 */
int8_t rtcc_set_autocalibration(uint8_t period);

/**
 * \brief Initialize the RTCC, configures the I2C bus, interrupts and registers
 * \return
 * \           AB08_SUCCESS date/time set
 * \           AB08_ERROR failed to set time/date (enable DEBUG for more info)
 */
int8_t rtcc_init(void);
/** @} */
/* -------------------------------------------------------------------------- */
#endif /* ifndef RTCC_H_ */
/* -------------------------------------------------------------------------- */
/**
 * @}
 * @}
 */