HCDS1302 - Library for DS1302 RTC modules

[admin]

Arduino library for DS1302 based real time clock modules. This library currently supports the following product(s):

DS1302 Real Time Clock Module (RTC) (SKU: HCMODU0035) https://hobbycomponents.com/rtc/348-ds1 ... ock-module



Using the library


Step 1) Downloading the library

Download (please login to download) the library as a zip file by clicking the link below:

HCDS1302_V1_0_0.zip

Save it to somewhere convenient on your computer.



Step 2) Installing the Library

Once downloaded, open up your Arduino IDE and go to Sketch->Include Library->Add .ZIP Library.

In the file selection dialogue window that opens up, navigate to wherever you downloaded the HCDS1302_Vx_x.zip file and select it, then click the ‘Open’ button.

Alternatively you can just unzip the library into your Arduino library folder usually found in the following location:


On Windows:
My Documents\Arduino\libraries\

On Mac:
Documents/Arduino/libraries/

Linux:
Usually found within the users home area under /Arduino/libraries/



Step 3) Including the library in your sketch

Adding the library to your sketch consists of 3 steps; Firstly, include the HCDS1302 file (HCDS1302.h) at the top of your sketch, define the Arduino pins connected to the DS1320, then finally create an instance of the library:

Code: [Select all] [Expand/Collapse]

1. // Step 1: Include the mLink library
2. #include "HCDS1302.h"
3.  
4. // Step 2: Define the Arduino pins that will be connected to the DS1302
5. #define CLK_PIN 4
6. #define DAT_PIN 3
7. #define RST_PIN 2
8.  
9. //Step 3: Create an instance of the library
10. HCDS1302 RTC(CLK_PIN, DAT_PIN, RST_PIN);
11.  
12.  
13. void setup()
14. {
15. }
16.  
17.  
18. void loop()
19. {
20. }

GeSHi © Codebox Plus Extension

Example sketches:

Set/Read DS1320 Example

Set and read back example:

This sketch demonstrates how to set and read back the DS1302s date
and time.

Please see Licence.txt in the library folder for terms of use.

Code: [Select all] [Expand/Collapse]

1. #include "HCDS1302.h"
2.  
3. // Define the pins connected to the DS1302
4. #define CLK_PIN 4
5. #define DAT_PIN 3
6. #define RST_PIN 2
7.  
8. // Create an instance of the library
9. HCDS1302 RTC(CLK_PIN, DAT_PIN, RST_PIN);
10.  
11.  
12. void setup()
13. {
14.   Serial.begin(9600);
15.  
16.   // Set the DS1302s time to 16:30:00
17.   RTC.setTime(16, 30, 0);
18.  
19.   // Set the DS1302s calendar to 7th Feb, 2024
20.   RTC.setDate(24, 2, 7);
21.  
22.   // Set the DS1302s day of the week
23.   RTC.dow(3);
24. }
25.  
26.  
27. void loop()
28. {
29.   // Read the current date & time
30.   RTC.update();
31.  
32.   // Get the last read time
33.   byte seconds = RTC.seconds();
34.   byte minutes = RTC.minutes();
35.   byte hours = RTC.hours();
36.  
37.   // Get the last read date
38.   byte date = RTC.date();
39.   byte month = RTC.month();
40.   byte year = RTC.year();
41.   byte dow = RTC.dow();
42.  
43.   // Print out the results
44.   Serial.print("Hours: "); Serial.println(hours);
45.   Serial.print("Minutes: "); Serial.println(minutes);
46.   Serial.print("Seconds: "); Serial.println(seconds);
47.   Serial.print("Year: "); Serial.println(year);
48.   Serial.print("Month: "); Serial.println(month);
49.   Serial.print("Date: "); Serial.println(date);
50.   Serial.print("DOW: "); Serial.println(dow);
51.   Serial.println();
52.  
53.   delay(1000);
54. }

GeSHi © Codebox Plus Extension

Formatted date and time example

Print a formatted date and time example:

This sketch demonstrates how to print out the current date and time
as a formatted string.

Please see Licence.txt in the library folder for terms of use.

Code: [Select all] [Expand/Collapse]

1. #include "HCDS1302.h"
2.  
3. // Define the pins connected to the DS1302
4. #define CLK_PIN 4
5. #define DAT_PIN 3
6. #define RST_PIN 2
7.  
8. // Create an instance of the library
9. HCDS1302 RTC(CLK_PIN, DAT_PIN, RST_PIN);
10.  
11.  
12. void setup()
13. {
14.   Serial.begin(9600);
15. }
16.  
17.  
18. void loop()
19. {
20.   // Create a string to print.
21.   // YY will be replaced by the year
22.   // MM will be replaced by the month
23.   // DD will be replaced by the date
24.   // hh will be replaced by the hour
25.   // mm will be replaced by the minutes
26.   // ss will be replaced by the seconds
27.   char exampleString[] = "Date: DD/MM/20YY Time: hh:mm:ss";
28.  
29.   // Read the current date & time
30.   RTC.update();
31.  
32.   RTC.dateTimeString(exampleString);
33.  
34.   Serial.println(exampleString); Serial.println();
35.  
36.   delay(1000);
37. }
38.  

GeSHi © Codebox Plus Extension

Write and read from RAM Example

Writing to and reading from the DS1302s RAM:

This sketch demonstrates how to write to and read back from the
DS1302s 31 bytes of RAM

Please see Licence.txt in the library folder for terms of use.

Code: [Select all] [Expand/Collapse]

1. #include "HCDS1302.h"
2.  
3. // Define the pins connected to the DS1302
4. #define CLK_PIN 4
5. #define DAT_PIN 3
6. #define RST_PIN 2
7.  
8. // Create an instance of the library
9. HCDS1302 RTC(CLK_PIN, DAT_PIN, RST_PIN);
10.  
11.  
12. void setup()
13. {
14.   Serial.begin(9600);
15.  
16.   // Write 0xAA to the 31 bytes of RAM
17.   for(byte address = 0; address <= 30; address++)
18.     RTC.ram(address, 0xAA);
19.  
20.  
21.   // Read back the RAM and print it out
22.   for(byte address = 0; address <= 30; address++)
23.   {
24.     Serial.print(RTC.ram(address), HEX);
25.     Serial.print(" ");
26.   }
27. }
28.  
29.  
30. void loop()
31. {
32.  
33. }

GeSHi © Codebox Plus Extension

HCDS1302 Library Functions:

RTC.update(void);

Reads the current date and time from the RTC.

Returns: void



RTC.seconds(void);

Gets the seconds from the last read of the RTC.

Returns:
A byte value containing the current second count (0 to 59).

Notes:
Note, to get the latest time the update() function should be run first.



RTC.minutes(void);

Gets the minutes from the last read of the RTC.

Returns:
A byte value containing the current minutes count (0 to 59).

Notes:
Note, to get the latest time the update() function should be run first.



RTC.hours(void);

Gets the hours from the last read of the RTC.

Returns:
A byte value containing the current hour count in 24 hr format (0 to 23).

Notes:
Note, to get the latest time the update() function should be run first.



RTC.date(void);

Gets the date from the last read of the RTC.

Returns:
A byte value containing the current date (1 to 31).

Notes:
Note, to get the latest date the update() function should be run first.



RTC.month(void);

Gets the month from the last read of the RTC.

Returns:
A byte value containing the current month (1 to 12).

Notes:
Note, to get the latest date the update() function should be run first.



RTC.year(void);

Gets the year from the last read of the RTC.

Returns:
A byte value containing the current year (0 to 99).

Notes:
Note, to get the latest date the update() function should be run first.



RTC.dow(void);

Gets the day of the week from the last read of the RTC.

Returns:
A byte value containing the current day of the week (1 to 7).

Notes:
Note, to get the latest dow the update() function should be run first.



RTC.dateTimeString(char *a);

Inserts the time and date into a formatted, null terminated character array where:

*a is a pointer to the start of the array.

If the character array contains the characters ss it will be replaced with the last read seconds count.
If the character array contains the characters mm it will be replaced with the last read minute count.
If the character array contains the characters hh it will be replaced with the last read hour count.
If the character array contains the characters DD it will be replaced with the last read date.
If the character array contains the characters MM it will be replaced with the last read month.
If the character array contains the characters YY it will be replaced with the last read year..

Returns:
void



RTC.setTime(byte h, byte m, byte s);

Sets the RTC time where:
h is the hour count
m is the minute count
s is the second count

Returns:
void



RTC.setDate(byte y, byte m, byte d);

Sets the RTC calander where:
y is the year
m is the month
d is the day

Returns:
void



RTC.seconds(byte value);

Sets the RTC seconds counter where:
value is the seconds to write. Valid values are 0 to 59.

Returns:
void



RTC.minutes(byte value);

Sets the RTC minute counter where:
value is the minutes to write. Valid values are 0 to 59.

Returns:
void



RTC.hours(byte value);

Sets the RTC hour counter where:
value is the hours to write. Valid values are 0 to 23.

Returns:
void



RTC.date(byte value);

Sets the RTC date where:
value is the date to write. Valid values are 0 to 31.

Returns:
void

Notes:
Setting invalid dates for the current day/month/year may lead to undefined behaviour of the RTC



RTC.month(byte value);

Sets the RTC month where:
value is the month to write. Valid values are 1 to 31.

Returns:
void

Notes:
Setting invalid dates for the current day/month/year may lead to undefined behaviour of the RTC



RTC.year(byte value);

Sets the RTC year where:
value is the year to write. Valid values are 1 to 12.

Returns:
void

Notes:
Setting invalid dates for the current day/month/year may lead to undefined behaviour of the RTC



RTC.dow(byte value);

Sets the RTC day of the week counter where:
value is the day of the week to write. Valid values are 1 to 7.

Returns:
void

Notes:
The day of the week counter is not assigned to any particular day or date.



RTC.writeProtect(boolean state);

Enables write protection for the RTC. When enabled the RTCs calendar and RAM cannot be updated. Valid values for state are:
WP_OFF write protection is off
WP_ON write protection is on

Returns:
void



RTC.trickleCharger(byte value);

Sets the battery charge current where:
value is the battery charge setting. Valid values are:

TC_DISABLED No charge current (default)
TC_DIODE_2K Battery is charged via a series diode and a 2K resistor connected to VCC
TC_DIODE_4K Battery is charged via a series diode and a 4K resistor connected to VCC
TC_DIODE_8K Battery is charged via a series diode and a 8K resistor connected to VCC
TC_DIODE_DIODE_2K Battery is charged via two series diodes and a 2K resistor connected to VCC
TC_DIODE_DIODE_4K Battery is charged via two series diodes and a 4K resistor connected to VCC
TC_DIODE_DIODE_8K Battery is charged via two series diodes and a 8K resistor connected to VCC

Returns:
void

Notes:
USE THIS FUNCTION WITH CAUTION: Before enabling battery charging you must confirm that your module is fitted with a rechargeable battery. Check your batteries datasheet for correct charging currents.

Each diode has a forward voltage of ~0.7V.



RTC.ram(void);

Returns the byte value stored in one of the RTCs RAM registers where:
add is the registers address. Valid values for address are 0 to 30

Returns:
A byte value containing the value stored at the specified address.



RTC.ram(byte add, byte data);

Writes a byte to one of the RTCs RAM registers where:
add is the registers address. Valid values for address are 0 to 30
data is the byte value to write

Returns:
void





Diagrams, libraries, and example code are provided as an additional free service by Hobby Components and are not sold as part of this product. We do no provide any guarantees or warranties as to their accuracy or fitness for purpose.

Descriptions and diagrams on this page are copyright Hobby Components Ltd and may not be reproduced without permission.