Library for the Dallas Semiconductor DS1307 RTC chip communicating on two-wire (also known as I2C) bus.
- Sensor has fixed address
0x68. - The library utilizes external custom data type from the application library
gbjAppHelpersas a datetime structure in the form of alias in own body. - The library does not provide any formatting and parsing functionality for datetime structures. Use the dedicated library
gbjAppHelpersfor those funcionalities. - Library caches configuration register of the chip.
- Connect microcontroller's pin
D0to sensor's pin SDA (Serial Data). - Connect microcontroller's pin
D1to sensor's pin SCL (Serial Clock).
- Connect microcontroller's pin
A4to sensor's pin SDA (Serial Data). - Connect microcontroller's pin
A5to sensor's pin SCL (Serial Clock).
- Connect microcontroller's pin
D2to sensor's pin SDA (Serial Data). - Connect microcontroller's pin
D1to sensor's pin SCL (Serial Clock).
- Particle.h: Includes alternative (C++) data type definitions.
- Arduino.h: Main include file for the Arduino SDK version greater or equal to 100.
- inttypes.h: Integer type conversions. This header file includes the exact-width integer definitions and extends them with additional facilities provided by the implementation.
- TwoWire: I2C system library loaded from the file
Wire.h.
- gbjMemory: Memory custom library loaded from the file
gbj_memory.h, which provides common memory processing functionality here utilizing non-volatile, battery backed up memory of the RTC chip. - gbjAppHelpers: Custom library loaded from the file gbj_apphelpers.h for a generic application logic. The library gbjDS1307 utilizes custom data type from it for datetime structure definition.
The library does not have specific error codes. Error codes as well as result code are inherited from the parent library only. The result code and error codes can be tested in the operational code with its method getLastResult(), isError() or isSuccess().
- Addresses::ADDRESS: I2C address of the RTC chip.
- SquareWaveFrequency::SQW_RATE_1HZ: Square wave frequency 1 Hz.
- SquareWaveFrequency::SQW_RATE_4KHZ: Square wave frequency 4096 Hz.
- SquareWaveFrequency::SQW_RATE_8KHZ: Square wave frequency 8192 Hz.
- SquareWaveFrequency::SQW_RATE_32KHZ: Square wave frequency 32768 Hz.
The library does not provide any own specific error codes. All result and error codes are inhereted for the parent library gbjMemory.
The configuration of the RTC chip is realized by the configuration register, which consists of several configuration bits determining its behavior and time keeping registers for seconds and hours determining running and form of time expression. The library stores (caches) the value of those registers in its instance object.
The chip configuration implemented in the library is based on updating cached configuration values in advanced by methods of the naming convention configXXX and finally sending that value to the chip and write all configuration bits to appropriate registers at once in order to reduce communication on the two-wire bus in contrast to sending configuration bits to the chip individually.
Because the RTC chip does not change the content of its configuration register and status bits of time keeping registers during operation on its own, it is not necessary to read those registers right before using getters. An application may rely on their cached values.
In a sketch the constants can be referenced in following forms:
- Static constant in the form
gbj_ds1307::<enumeration>::<constant>or shortlygbj_ds1307::<constant>, e.g., gbj_ds1307::SquareWaveFrequency::SQW_RATE_32KHZ or gbj_ds1307::SquareWaveFrequency::SQW_RATE_32KHZ. - Instance constant in the form
<object>.<constant>, e.g., object.SQW_RATE_32KHZ.
gbj_ds1307 device = gbj_ds1307();
setup()
{
begin(device.AT24C512, device.ADDRESS_5);
}- setDateTime()
- setConfiguration()
- configClockEnable()
- configClockDisable()
- configSqwEnable()
- configSqwDisable()
- configSqwLevelHigh()
- configSqwLevelLow()
- configSqwRate()
- getConfiguration()
- getPowerUp()
- getDateTime()
- getClockEnabled()
- getClockMode12H()
- getSqwRate()
- getSqwLevel()
- getSqwEnabled()
Other possible setters and getters are inherited from the predecessor libraries and described there.
The library does not need special constructor and destructor, so that the inherited ones are good enough and there is no need to define them in the library, just use it with default or specific parameters as defined at constructor of parent library.
- Constructor sets parameters specific to the two-wire bus in general.
- All the constructor parameters can be changed dynamically with corresponding setters later in a sketch.
- Although the datasheet for the RTC chip claims it work on 100 kHz frequency of the two-wire bus, an experiments proved, that it works on 400 kHz frequency as well. So that the constructor does not force the 100 kHz frequency, just default it.
gbj_ds1307(ClockSpeeds clockSpeed, uint8_t pinSDA, uint8_t pinSCL)
-
clockSpeed: Two-wire bus clock frequency in Hertz.
- Valid values: ClockSpeeds::CLOCK_100KHZ, ClockSpeeds::CLOCK_400KHZ
- Default value: ClockSpeeds::CLOCK_100KHZ
-
pinSDA: Microcontroller's pin for serial data. It is not a board pin but GPIO number. For hardware two-wire bus platforms it is irrelevant and none of methods utilizes this parameter for such as platforms for communication on the bus. On the other hand, for those platforms the parameters might be utilized for storing some specific attribute in the class instance object.
- Valid values: positive integer
- Default value: 4 (GPIO4, D2)
-
pinSCL: Microcontroller's pin for serial clock. It is not a board pin but GPIO number. For hardware two-wire bus platforms it is irrelevant and none of methods utilizes this parameter for such as platforms. On the other hand, for those platforms the parameters might be utilized for storing some specific attribute in the class instance object.
- Valid values: positive integer
- Default value: 5 (GPIO5, D1)
Object performing the sensor management. The constructor cannot return a result or error code directly, however, it stores them in the instance object.
The method initiates the RTC chip and two-wire bus.
- The method sets parameters of non-volatile memory and reads configuration register to its cache..
ResultCodes begin()
None
Some of result or error codes.
The particular method sets the date and time to the RTC chip and starts its internal oscillator.
- The method is overloaded, either for flashed strings or strings in SRAM pointers for date and time.
- The method sets datetime regardless the RTC chip is running or not.
- If no input parameters are used, just the CH bit of seconds time keeping register is set with retaining current second.
- The methods are useful at using the compilation __DATE__ and __TIME__ constants.
ResultCodes startClock(const char* strDate, const char* strTime, uint8_t weekday, bool mode12h)
ResultCodes startClock(const __FlashStringHelper* strDate, const __FlashStringHelper* strTime, uint8_t weekday = 1, bool mode12h = false)
ResultCodes startClock()
-
strDate: Pointer to a system date formatted string.
- Valid values: address range
- Default value: none
-
strTime: Pointer to a system time formatted string.
- Valid values: address range
- Default value: none
-
weekday: Number of current day in a week. It is up to an application to set the starting day in the week. If weekdays are irrelevant, the default value may be used. The provided weekday fallbacks to valid range.
- Valid values: 1 ~ 7
- Default value: 1
-
mode12h: Flag about using 12 hours mode.
- Valid values: true = 12 hours mode, false = 24 hours mode
- Default value: false (24 hours mode)
Some of result or error codes.
gbj_ds1307 device = gbj_ds1307();
device.startClock(__DATE__, __TIME__, 3); // 24h mode
device.startClock(__DATE__, __TIME__, 3, true); // 12h mode
device.startClock(F(__DATE__), F(__TIME__)); // Flashed strings
device.startClock(); // Start just internal oscillatorThe method resets CH bit of the seconds time keeping register with retaining current second in it.
ResultCodes stopClock()
None
Some of result or error codes.
The method enables generating square wave signal on SQW/OUT pin of the RTC chip at frequency determined by the input parameter and starts the clock.
- The method sends new value of the control register or seconds time keeping register to the chip only if cached value differs from desired one in order to avoid useless communication on the two-wire bus.
ResultCodes startSqw()
- rate: Value of pair of RS1 and RS0 bits. It fallbacks to least significant 2 bits.
- Valid values: SquareWaveFrequency::SQW_RATE_1HZ ~ SquareWaveFrequency::SQW_RATE_32KHZ
- Default value: SquareWaveFrequency::SQW_RATE_32KHZ
Some of result or error codes.
The method sanitizes datetime parameters taken from referenced external structure (datetime record) and writes them to the RTC chip.
- The method strips century from the year and writes just two-digit year number.
- The method writes cached value to the control register of the chip as well, so that the chip can be set, started and configured at once.
ResultCodes setDateTime(const Datetime &dtRecord)
- dtRecord: Referenced structure variable for desired date and time defined in the library gbjAppHelpers and declared as an alias.
- Valid values: as described for the library gbjAppHelpers
- Default value: none
Some of result or error codes.
gbj_ds1307 device = gbj_ds1307()
gbj_ds1307::Datetime rtcDateTime;
void setup()
{
rtcDateTime.year = 2018;
rtcDateTime.month = 12;
rtcDateTime.day = 26;
rtcDateTime.weekday = 3;
rtcDateTime.hour = 0;
rtcDateTime.minute = 54;
rtcDateTime.second = 32;
rtcDateTime.mode12h = true;
rtcDateTime.pm = false;
//
device.setDateTime(rtcDateTime);
}The method converts already read datetime from the chip and stored in instance internal structure to the referenced external structure (datetime record).
- The method converts recently read datetime from the chip without repeating the reading from it. It is useful right after begin() method, which reads the chip's status in either case.
- The method expects 21th century, so that adds 2000 to the read two-digit year number.
void convertDateTime(Datetime &dtRecord)
- dtRecord: Referenced structure variable for placing read date and time defined in the library gbjAppHelpers and declared as an alias.
- Valid values: as described for the library gbjAppHelpers
- Default value: none
None
The method reads datetime from the RTC chip, converts it and place it to the referenced external structure (datetime record).
- The method reads configuration register to its cache as well.
ResultCodes getDateTime(Datetime &dtRecord)
- dtRecord: Referenced structure variable for placing read date and time defined in the library gbjAppHelpers and declared as an alias.
- Valid values: as described for the library gbjAppHelpers
- Default value: none
Some of result or error codes.
The method writes the new content of the configuration register stored in the instance object (configuration cache) to the chip. This content should has been prepared by methods of names configXXX right before.
ResultCodes setConfiguration()
None
Some of result or error codes.
The method provides content of the configuration register from its cache read or updated recently.
uint8_t getConfiguration()
None
Content of the configuration register cache.
The particular method sets or resets clock halt (CH) bit of the seconds time keeping register. After setting this bit by sending date and time to the chip, its internal oscillator is started or stopped and real time clock is running or halted.
- The status of the CH bit is sent to the chip by the method setDateTime(), but this method does not change the CH bit on its own and retains the value set by particular
configClockXXXmethod. - The status of the CH bit is set and sent to the chip by the method startClock() as well, but in this case this method sets it to enable the clock running (it calls
configClockEnable()by itself).
void configClockEnable()
void configClockDisable()
None
None
The particular method sets or resets SQWE bit in the configuration register cache. After sending that cached value to the chip, the generating of square wave signal on the SQW/OUT pin of the chip starts or stops.
void configSqwEnable()
void configSqwDisable()
None
None
configSqwLevelHigh(), configSqwLevelLow()
The particular method sets or resets OUT bit in the configuration register cache. It determines stable level of the SQW/OUT pin of the chip when generating square wave signal is disabled.
void configSqwLevelHigh()
void configSqwLevelLow()
None
None
configSqwEnable(), configSqwDisable()
The method sets RS0, RS1 bits in the configuration register cache. It determines frequency of the generated square wave signal on the SQW/OUT pin when the generating is enabled. The particular frequency is determined by corresponding library constant.
void configSqwRate(SquareWaveFrequency rate)
- rate: Value of pair of RS1 and RS0 bits. It fallbacks to least significant 2 bits.
- Valid values: SquareWaveFrequency::SQW_RATE_1HZ ~ SquareWaveFrequency::SQW_RATE_32KHZ
- Default value: None
None
configSqwEnable(), configSqwDisable()
The method provides flag determining that the configuration register has the value typical for its power-up content. It does not necessary mean, that the chip has been turned off and on, just the configuration register values are the same.
bool getPowerUp()
None
Flag about content of the configuration register typical for power-up state.
The method provides flag whether the CH bit of the seconds time keeping register is set or not, i.e., whether the internal oscillator of the chip and real time clock is running or not.
bool getClockEnabled()
None
Flag about running real time clock.
configClockEnable(), configClockDisable()
The method provides flag whether the 12 hours mode bit in the hours time keeping register is set or not, i.e., whether the time is expressed in 12 or 24 hours form.
bool getClockMode12H()
None
Flag about active 12 hours mode.
The method provides current set square wave frequency regardless if the generating is enabled and running or not.
SquareWaveFrequency getSqwRate()
None
SQW frequency in form of one of the library constants SquareWaveFrequency::SQW_RATE_1HZ ~ SquareWaveFrequency::SQW_RATE_32KHZ.
The method provides output level of the SQW/OUT pin of the chip when the generating of square wave signal is disabled.
uint8_t getSqwLevel()
None
Output level 1 or 0, i.e., HIGH or LOW.
configSqwLevelHigh(), configSqwLevelLow()
configSqwEnable(), configSqwDisable()
The method provides flag whether the SQWE bit of the configuration register is set or not, i.e., whether the generating of the square wave signal is enabled or not.
bool getSqwEnabled()
None
Flag about enabled square wave signal generation.