Subversion Repositories idreammicro-avr

/**************************************************************************//**
 * \brief DS1307 RTC library
 * \author Copyright (C) 2011  Julien Le Sech - www.idreammicro.com
 * \version 1.0
 * \date 20090501
 *
 * This file is part of the iDreamMicro library.
 *
 * This library is free software: you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License as published by the Free
 * Software Foundation, either version 3 of the License, or (at your option) any
 * later version.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 * details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program. If not, see http://www.gnu.org/licenses/
 ******************************************************************************/

/**************************************************************************//**
 * \headerfile ds1307.h
 ******************************************************************************/

#ifndef H__IDREAMMICRO__DS1307__H
#define H__IDREAMMICRO__DS1307__H

#ifdef _cplusplus
extern "C"{
#endif

/******************************************************************************
 * Header file inclusions.
 ******************************************************************************/

#include <useful/datetime.h>

#include <stdbool.h>

/******************************************************************************
 * Public macro definitions.
 ******************************************************************************/

/**************************************************************************//**
 * \def     DS1307__CLOCK_RATE
 * \brief   DS1307 frequency in Hertz.
 ******************************************************************************/
#define DS1307__CLOCK_RATE  100000

/******************************************************************************
 * Public type definitions.
 ******************************************************************************/

/**************************************************************************//**
 * \enum    ds1307__hour_modes.
 * \brief   RTC hour modes.
 *
 * \typedef ds1307__hour_mode_t.
 * \brief   RTC hour mode.
 ******************************************************************************/
typedef enum ds1307__hour_modes
{
    DS1307__HOUR_MODE__24_HOUR = 0, /*!< 24-hour mode. */
    DS1307__HOUR_MODE__12_HOUR = 1  /*!< 12-hour mode. */
} ds1307__hour_mode_t;

/**************************************************************************//**
 * \enum    ds1307__sqw_out_levels
 * \brief
 *
 * \typedef ds1307__sqw_out_level_t
 * \brief
 ******************************************************************************/
typedef enum ds1307__sqw_out_levels
{
    DS1307__SQW_LEVEL__LOW, /*!< Low level. */
    DS1307__SQW_LEVEL__HIGH /*!< High level. */
} ds1307__sqw_out_level_t;

/**************************************************************************//**
 * \enum    ds1307__sqw_out_frequencies
 * \brief
 *
 * \typedef ds1307__sqw_out__frequency_t
 * \brief
 ******************************************************************************/
typedef enum ds1307__sqw_out_frequencies
{
    DS1307__SQW_FREQUENCY__1_HZ,
    DS1307__SQW_FREQUENCY__4096_HZ,
    DS1307__SQW_FREQUENCY__8192_HZ,
    DS1307__SQW_FREQUENCY__32768_HZ
} ds1307__sqw_out__frequency_t;

/******************************************************************************
 * Public function prototypes.
 ******************************************************************************/

/**************************************************************************//**
 * \fn void ds1307__initialize(void)
 *
 * \brief Initialize DS1307 RTC.
 ******************************************************************************/
void
ds1307__initialize
(
    void
);

/**************************************************************************//**
 * \fn void ds1307__get_time(
 * date_time__time_t*   p_time,
 * ds1307__hour_mode_t* p_hour_mode)
 *
 * \brief Get RTC time.
 *
 * \param p_time a pointer to fill with RTC time
 * \param p_hour_mode a pointer to fill with RTC hour mode
 ******************************************************************************/
void
ds1307__get_time
(
    datetime__time_t*      p_time,
    ds1307__hour_mode_t*    p_hour_mode
);

/**************************************************************************//**
 * \fn void ds1307__set_time(
 * date_time__time_t* p_time,
 * ds1307__hour_mode_t hour_mode)
 *
 * \brief Set RTC time.
 *
 * \param p_time time to set. p_time->meridiem isn't used in 12-hour mode.
 * \param hour_mode hour mode
 ******************************************************************************/
void
ds1307__set_time
(
    datetime__time_t*  p_time,
    ds1307__hour_mode_t hour_mode
);

/**************************************************************************//**
 * \fn void ds1307__get_date(date_time__date_t* p_date)
 *
 * \brief Get RTC date.
 *
 * \param p_date a pointer to fill with RTC date
 ******************************************************************************/
void
ds1307__get_date
(
    datetime__date_t* p_date
);

/**************************************************************************//**
 * \fn void ds1307__set_date(date_time__date_t* p_date)
 *
 * \brief Set RTC date.
 *
 * \param p_date date to set
 ******************************************************************************/
void
ds1307__set_date
(
    datetime__date_t* p_date
);

/**************************************************************************//**
 * \fn void ds1307__set_square_wave_output_level(ds1307__sqw_out_level_t level)
 *
 * \brief Set square wave output pin level.
 *
 * \param level Level to set.
 ******************************************************************************/
void
ds1307__set_square_wave_output_level
(
    ds1307__sqw_out_level_t level
);

/**************************************************************************//**
 * \fn void ds1307__set_square_wave_output_signal(
 * ds1307__sqw_out__frequency_t    frequency,
 * bool                            enable)
 *
 * \brief Set Square-Wave output signal.
 *
 * \param   frequency   Frequency.
 * \param   enable      Status.
 ******************************************************************************/
void
ds1307__set_square_wave_output_signal
(
    ds1307__sqw_out__frequency_t    frequency,
    bool                            enable
);

/**************************************************************************//**
 * \fn uint8_t ds1307__read_byte_in_ram(uint8_t address)
 *
 * \brief Read a byte in DS1307 RAM.
 *
 * \param address Address to read.
 *
 * \return Read byte.
 ******************************************************************************/
uint8_t
ds1307__read_byte_in_ram
(
    uint8_t address
);

/**************************************************************************//**
 * \fn void ds1307__read_bytes_in_ram(
 * uint8_t  address,
 * uint8_t  length,
 * uint8_t* p_data)
 *
 * \brief Read bytes in DS1307 RAM.
 *
 * \param       address Address to read.
 * \param       length  Number of bytes to read.
 * \param[in]   p_data  Buffer to fill.
 ******************************************************************************/
void
ds1307__read_bytes_in_ram
(
    uint8_t     address,
    uint8_t     length,
    uint8_t*    p_data
);

/**************************************************************************//**
 * \fn void ds1307__write_byte_in_ram(uint8_t address, uint8_t data)
 *
 * \brief Write a byte in DS1307 RAM.
 *
 * \param address   Address to write.
 * \param data      Byte to write.
 ******************************************************************************/
void
ds1307__write_byte_in_ram
(
    uint8_t address,
    uint8_t data
);

/**************************************************************************//**
 * \fn void ds1307__write_bytes_in_ram(uint8_t address, uint8_t data)
 *
 * \brief Write a byte in DS1307 RAM.
 *
 * \param       address Address to write.
 * \param       length  Number of bytes to write.
 * \param[in]   p_data  Bytes to write.
 ******************************************************************************/
void
ds1307__write_bytes_in_ram
(
    uint8_t     address,
    uint8_t     length,
    uint8_t*    p_data
);

#ifdef _cplusplus
}
#endif

#endif /* H__IDREAMMICRO__DS1307__H */