Functions

ds3231.h File Reference

#include <avr/io.h>
#include "config.h"
#include <util/delay.h>
#include <util/delay_basic.h>
#include "i2c.h"

Go to the source code of this file.

Functions

void reset_rtc_i2c (void)
 Resets the I2C to RTC communications.
uint8_t read_from_rtc (uint8_t *store_data)
 Read a set of data from the DS3231 Real time clock to memory.
uint8_t write_to_rtc (uint8_t *store_data)
 Write a set of data from memory to the DS3231 Real time clock.
uint8_t write_alarm (uint8_t *alarm_data)
 Write a set of data from memory to the alarm registers on the DS3231 Real time clock.
uint8_t read_temp_from_rtc (uint8_t *store_data)
 Read a temperature from the DS3231 internal temp sensor.
uint8_t set_rtc_register_pointer (uint8_t val)
 Set the register pointer in the RTC to the parameter supplied.
uint32_t get_fattime (void)
 Reads the time into internal variable time_store[7], and converts for FAT filesystems.
void dirname_from_date (uint8_t *dirname, uint8_t *time_store)
 Convert a time read from the RTC into a directory name. DOESN'T READ THE RTC.
void filename_from_date (uint8_t *filename, uint8_t *time_store)
 Convert a time read from the RTC into a file name. DOESN'T READ THE RTC.
void iso_time (uint8_t *iso_time_store, uint8_t *time_store)
 Create an ISO time string from a set of data. DOESN'T READ THE RTC.
void americandate (uint8_t *result, uint8_t *time_store)
 Create a string representing the data in the form mm/dd/yyyy from a set of data. DOESN'T READ THE RTC.
void hms_time (uint8_t *result, uint8_t *time_store)
 Create an ISO time string from a set of data read from the RTC.
uint8_t hex2ascii_h (uint8_t hexval)
 Convert the high nibble of a supplied byte into an ASCII character.
uint8_t hex2ascii_l (uint8_t hexval)
 Convert the low nibble of a supplied byte into an ASCII character.
uint8_t bcd_to_hex (uint8_t bcd)
 Convert a BCD value in a byte to the correct hex value.
uint8_t set_datetime (uint8_t *iso_time_store)
 Take in a pointer to time in ISO format (15 bytes) eg 20101203 141604 and set RTC to that time. Time format is xxyymmddxhhmmss where xx and x are don't care Time format does not need to be null terminated Day of week on RTC is set to 1, as I never use dow.
void addtime (uint8_t *result, uint8_t *start, uint16_t seconds)
 Take a BCD time eg as read from rtc, in form ss,mm,hh supplied as *start and add seconds seconds to it putting the result in *result OFFSET BY 1 Note that it only works for hh:mm:ss, not days, and also that hh will wrap.

Function Documentation

void addtime ( uint8_t *  result,
uint8_t *  start,
uint16_t  seconds 
)

Take a BCD time eg as read from rtc, in form ss,mm,hh supplied as *start and add seconds seconds to it putting the result in *result OFFSET BY 1 Note that it only works for hh:mm:ss, not days, and also that hh will wrap.

Parameters:
result pointer to location for resulting bcd 4 bytes: dummy,ss,mm,hh
start Pointer to start time as bcd 3 bytes: ss,mm,hh
seconds number of seconds to add to start to create result
void americandate ( uint8_t *  result,
uint8_t *  time_store 
)

Create a string representing the data in the form mm/dd/yyyy from a set of data. DOESN'T READ THE RTC.

Parameters:
*time_store Pointer to the 7 byte data to be converted Order of RTC values in time_store is ss,mm,hh,dow,dd,mm,yy valid dow is 1-7
*result Pointer to 11 byte result

note that this function doesn't read the time, or modify time_store

uint8_t bcd_to_hex ( uint8_t  bcd  ) 

Convert a BCD value in a byte to the correct hex value.

Parameters:
bcd uint8_t value in BCD
Returns:
returns uint8_t hex value converted from BCD

For example, 23 -> 0x17

void dirname_from_date ( uint8_t *  dirname,
uint8_t *  time_store 
)

Convert a time read from the RTC into a directory name. DOESN'T READ THE RTC.

Parameters:
dirname Pointer to directory name. Directory name MUST be at least 8 characters + terminating null
time_store Pointer to the 7 byte time data

note that this function doesn't read the time, or modify time_store The first character of the directory name is unchanged Creates a dirname xyymddhh where x is left unchanged The month is converted to an ASCII character as 1 hex digit (december=C for example) So for example a directory name xxxxxxxx plus a time such as 3rd Dec 2010 at 14:16:04 is converted to the characters x10C0314

void filename_from_date ( uint8_t *  filename,
uint8_t *  time_store 
)

Convert a time read from the RTC into a file name. DOESN'T READ THE RTC.

Parameters:
*filename Pointer to file name. File name MUST be at least 12 characters + terminating null
*time_store Pointer to the 7 byte data to be converted

note that this function doesn't read the time, or modify time_store The first character of the filename is unchanged Creates a filename xmddhhmm where x is left unchanged The month is converted to an ASCII character as 1 hex digit (december=C for example) So for example a file name xxxxxxxx.zyx plus a time such as 3rd Dec 2010 at 14:16:04 is converted to the characters xC031416.zyx

Convert a time read from the RTC into a file name. DOESN'T READ THE RTC.

Parameters:
*time_store memory location of 7 bytes of the time to be converted.
*filename filename name to be created or overwritten.

Note that this function only converts. It doesn't update *time_store with the correct time

IMPORTANT Several characters of filename are NOT changed or set. Make sure you set it to a valid character or the filesystem will generate an error.

filename is overwritten with ^mddhhmm^ss^ where positions with ^ are unchanged m is month 1-12 value expressed as a single Hex character (eg C for December). Other values (BCD from the clock) are copied as is, without any conversion.

eg filename ABCDEFGH.XYZ plus date (15th December 2010) 20101215 13:16:56 -> AC151316.56Z

Note that both time_store and filename must exist in memory as arrays of 7 and 12 (or more) bytes respectively. To use the filename as a string, use a 13 byte array and null the 13th, or create filename as a string of the correct length.

uint32_t get_fattime ( void   ) 

Reads the time into internal variable time_store[7], and converts for FAT filesystems.

Returns:
Returns the current time as a a 32 bit value formatted correctly for FAT filesystems, eg FATFS

Reads the time into internal variable time_store[7], and converts for FAT filesystems.

Returns:
uint32_t FAT time encoded in a 32 bit value

See FATFS documentation for the specification of FAT time stamp format time_store must consist of an array of at least 7 bytes A side effect of calling this function is to update the time stores in time_store Format of time_store is (in BCD) ss,mm,hh,date,month,dow,yy

uint8_t hex2ascii_h ( uint8_t  hexval  ) 

Convert the high nibble of a supplied byte into an ASCII character.

Parameters:
hexval Hex value
Returns:
ASCII character of top nibble
uint8_t hex2ascii_l ( uint8_t  hexval  ) 

Convert the low nibble of a supplied byte into an ASCII character.

Parameters:
hexval Hex value
Returns:
ASCII character of bottom nibble
void hms_time ( uint8_t *  result,
uint8_t *  time_store 
)

Create an ISO time string from a set of data read from the RTC.

Parameters:
*result Pointer to 9 byte result which is null terminated and of form hh:mm:ss
*time_store Pointer to the 7 byte data to be converted (only first 3 bytes used) in order ss,mm,hh Order of RTC values in time_store is ss,mm,hh,dow,dd,mm,yy valid dow is 1-7

note that this function doesn't read the time, or modify time_store

void iso_time ( uint8_t *  iso_time_store,
uint8_t *  time_store 
)

Create an ISO time string from a set of data. DOESN'T READ THE RTC.

Parameters:
*iso_time_store Pointer to 16 byte result
*time_store Pointer to the 7 byte data to be converted Order of RTC values in time_store is ss,mm,hh,dow,dd,mm,yy valid dow is 1-7

note that this function doesn't read the time, or modify time_store A time such as 3rd Dec 2010 at 14:16:04 is converted from 0x04,0x16,0x14,dow,0x03,0x12,0x10 to the string "20101203 141604" with a trailing zero

Create an ISO time string from a set of data. DOESN'T READ THE RTC.

Parameters:
*time_store memory location of 7 bytes of the time to be converted.
*iso_time_store memory location for the 16 byte result.

Note that this function only converts. It doesn't update *time_store with the correct time

time_store format is ss,mm,hh,dd,mm,dow,yy yy counts from 2000 iso_time_store shows "20yymmdd hhmmss" 16 bytes including trailing null making it a string.

uint8_t read_from_rtc ( uint8_t *  store_data  ) 

Read a set of data from the DS3231 Real time clock to memory.

Parameters:
*store_data Pointer to location of 7 bytes to store RTC values Order of RTC values in time_store is ss,mm,hh,dow,dd,mm,yy valid dow is 1-7
Returns:
Returns the I2C error code from the transaction. 0=success.
uint8_t read_temp_from_rtc ( uint8_t *  store_data  ) 

Read a temperature from the DS3231 internal temp sensor.

Parameters:
*store_data Pointer to 2 bytes of storage for the result. First byte temp as signed 8 bit hex value, second byte fraction of 1C (top 2 bits)
Returns:
Returns the I2C error code from the transaction. 0=success.
void reset_rtc_i2c ( void   ) 

Resets the I2C to RTC communications.

uint8_t set_datetime ( uint8_t *  iso_time_store  ) 

Take in a pointer to time in ISO format (15 bytes) eg 20101203 141604 and set RTC to that time. Time format is xxyymmddxhhmmss where xx and x are don't care Time format does not need to be null terminated Day of week on RTC is set to 1, as I never use dow.

Parameters:
iso_time_store pointer to 15 bytes holding time as ISO value
Returns:
Error code from I2C transaction. 0 = success.

Take in a pointer to time in ISO format (15 bytes) eg 20101203 141604 and set RTC to that time. Time format is xxyymmddxhhmmss where xx and x are don't care Time format does not need to be null terminated Day of week on RTC is set to 1, as I never use dow.

Parameters:
*iso_time_store pointer to memory location holding time as 15 bytes.
uint8_t set_rtc_register_pointer ( uint8_t  val  ) 

Set the register pointer in the RTC to the parameter supplied.

Parameters:
val The address to be set
Returns:
Returns the I2C error code from the transaction. 0=success.
uint8_t write_alarm ( uint8_t *  alarm_data  ) 

Write a set of data from memory to the alarm registers on the DS3231 Real time clock.

Parameters:
*alarm_data Pointer to location of 9 bytes (first byte padding 0x07) from which to get values to send to alarm See datasheet for order of RTC values for alarm1,alarm2, control Note that the alarm control bits are the top bits of the alarm values.
Returns:
Returns the I2C error code from the transaction. 0=success.
uint8_t write_to_rtc ( uint8_t *  store_data  ) 

Write a set of data from memory to the DS3231 Real time clock.

Parameters:
*store_data Pointer to location of 8 bytes (first byte must be 0) from which to write RTC values Order of RTC values for setting time is 0,ss,mm,hh,dow,dd,mm,yy valid dow is 1-7
Returns:
Returns the I2C error code from the transaction. 0=success.