HCRTC - Arduino library for use with DS1307 based RTC module

[admin]

Real Time Clock module HCMODU0011


Description:

This Arduino library has been written to allow easy use DS1307 based real time clock modules such as our RTC module HCMODU0011. The library also contains functions to read and write to EEPROM memory which is also included in this RTC module. Communication with the module is via the standard Arduino I2C interface on pins A4 (SDA) & A5 (SCL) for an Uno, or 20 (SDA) & 21 (SCL) for a Mega.

You will need to download (please log in to download the library) and unzip this library to the Aduino development environments library area

On Windows:
My Documents\Arduino\libraries\
My Documents\Arduino\libraries\
My Documents\Arduino\libraries\

On Mac:
Documents/Arduino/libraries/
Documents/Arduino/libraries/
Documents/Arduino/libraries/
or similarly for Linux.


To use the library just include the Wire.h and HCRTC.h libraries and create an instance of the HCRTC library. E.g:

HCRTC HCRTC;

You can set the date and time with the following library function:

HCRTC.RTCWrite(I2C address, Year, Month, Day, Hour, Minuite, Second, Day of week);

And read the current date and time with the following library function:

HCRTC.RTCRead(I2C address);

Once the data has been read from the RTC module it can be accessed with the following library functions which return one byte of data of type byte:

HCRTC.GetDay()
HCRTC.GetMonth()
HCRTC.GetYear()
HCRTC.GetHour()
HCRTC.GetMinute()
HCRTC.GetSecond()
HCRTC.GetWeekday()

Or using the following string functions which return the time and date as a formatted string:

HCRTC.GetTimestring()
HCRTC.GetDatestring()

To write data (of type byte) to the modules EEPROM memory you can use the following sequence of library functions:

HCRTC.EEStartWrite(EEPROM I2C address, EEPROM memory start location);

HCRTC.EEWriteByte(Data byte 0);
HCRTC.EEWriteByte(Data byte 1);
.
.
HCRTC.EEWriteByte(Data byte n);

HCRTC.EEEndWrite();

Please note that when writing to the EEPROM, the data is temporarily stored in the EEPROM's cache memory until the HCRTC.EEEndWrite() function is executed. The maximum amount of data that this cache can hold in one write sequence is 64 bytes. You should therefore not attempt to write more than this ammount in one write sequence.


To read data (of type byte) from the modules EEPROM memory you can use the following read sequence:

HCRTC.EEStartRead(EEPROM I2C address, EEPROM memory start location);

Data_1 = HCRTC.EEReadByte(Data byte 0);
Data_2 = HCRTC.EEReadByte(Data byte 1);
.
.
Data_n = HCRTC.EEReadByte(Data byte n);

Example Code:

Code: [Select all] [Expand/Collapse]

1. /* FILE     HCRTC_Example.cpp
2.    DATE:    23/12/13
3.    VERSION: 0.2
4.    AUTHOR:  Andrew Davies
5.  
6. This is an example of how to use the Hobby Components RTC library to read and
7. write to and from the DS1307 real time clock 24C32 EEPROM. The library is intended
8. to be used with our RTC clock module (HCMODU0011), but should work fine with any
9. module that uses a DS1307 device.
10.  
11. You may copy, alter and reuse this code in any way you like, but please leave
12. reference to HobbyComponents.com in your comments if you redistribute this code.
13. This software may not be used directly for the purpose of selling products that
14. directly compete with Hobby Components Ltd's own range of products.
15.  
16. THIS SOFTWARE IS PROVIDED "AS IS". HOBBY COMPONENTS MAKES NO WARRANTIES, WHETHER
17. EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
18. MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ACCURACY OR LACK OF NEGLIGENCE.
19. HOBBY COMPONENTS SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR ANY DAMAGES,
20. INCLUDING, BUT NOT LIMITED TO, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES FOR ANY
21. REASON WHATSOEVER.
22. */
23.  
24.  
25. /* Include the wire library */
26. #include "Wire.h"
27. /* Include the Hobby Components RTC library */
28. #include <HCRTC.h>
29.  
30. /* Define the I2C addresses for the RTC and EEPROM */
31. #define I2CDS1307Add 0x68
32. #define I2C24C32Add  0x50
33.  
34. /* Example string to write to EEPROM */
35. char ExampleString[] = "Hobby Components";
36.  
37. /* Used in example as an index pointer */
38. byte index;
39.  
40. /* Create an instance of HCRTC library */
41. HCRTC HCRTC;
42.  
43.  
44. void setup()
45. {
46.   Serial.begin(9600);
47.  
48.   /* Use the RTCWrite library function to set the time and date.
49.      Parameters are: I2C address, year, month, date, hour, minute, second,
50.      day of week */
51.   HCRTC.RTCWrite(I2CDS1307Add, 13, 4, 24, 14, 21, 0, 3);
52. }
53.  
54. void loop()
55. {
56.   /************* Example write to EEPROM ***************/  
57.  
58.   /* Initiate a write sequence.
59.      Parameters are: I2C address, EEPROM start location */
60.   HCRTC.EEStartWrite(I2C24C32Add, 32000);
61.  
62.   for (index = 0; index < sizeof(ExampleString); index++)
63.   {  
64.     /* Sequentially write example data to the EEPROM */
65.     HCRTC.EEWriteByte(ExampleString[index]);
66.   }
67.   /* End the write sequence */
68.   HCRTC.EEEndWrite();
69.  
70.   /* Wait for cached data to finish writing */
71.   delay(10);  
72.  
73.  
74.   /************* Example read from EEPROM ***************/  
75.  
76.   /* Initiate read sequence.
77.      Parameters are: I2C address, EEPROM start location */
78.   HCRTC.EEStartRead(I2C24C32Add, 32000);
79.  
80.  
81.   for (index = 0; index < sizeof(ExampleString); index++)
82.   {
83.     /* Sequentially read data from EEPROM and output it to the UART */
84.     Serial.write(HCRTC.EEReadByte(I2C24C32Add));
85.   }    
86.   Serial.println();
87.    
88.  
89.   /* Continuously read the current time and date from the RTC */
90.   while(true)
91.   {
92.     /* Read the current time from the RTC module */
93.     HCRTC.RTCRead(I2CDS1307Add);
94.    
95.     /* Output the information to the UART */
96.     Serial.print(HCRTC.GetDay());
97.     Serial.print("/");
98.     Serial.print(HCRTC.GetMonth());
99.     Serial.print("/");
100.     Serial.print(HCRTC.GetYear());
101.     Serial.print(" ");
102.    
103.     Serial.print(HCRTC.GetHour());
104.     Serial.print(":");
105.     Serial.print(HCRTC.GetMinute());
106.     Serial.print(":");
107.     Serial.print(HCRTC.GetSecond());
108.     Serial.print(" DOW:");
109.     Serial.println(HCRTC.GetWeekday());
110.    
111.     /* Now output the same thing but using string functions instead: */
112.     Serial.print(HCRTC.GetDatestring());
113.     Serial.print(" ");
114.     Serial.println(HCRTC.GetTimestring());
115.    
116.     /* Wait a second before reading again */
117.     delay(1000);  
118.   }
119. }

GeSHi © Codebox Plus Extension

Library:

Latest version (0.4)

HCRTC.zip

Older versions:
V0.3

HCRTC.zip

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.

[DAJ]

HCRTC.zip

The header file in the library HCRTC.h explicitly includes "wire.h".

Note that the standard Arduino file is named "Wire.h" with an upper-case 'W'. There is not "wire.h".

If you're building on Windows that won't matter at all because the filesystems on Windows are not case-sensitive. If you're building on Linux (or, I think, MacOS) filenames are case-sensitive, the compiler won't find the file, and the build will fail.

[admin]

Thanks, I've made the correction and attached the new version to the first post.

[ftlpilot]

HCRTC.zip link has a virus/is unavailable - NOT VERY IMPRESSIVE

[andrew]

The library is just a zip file containing plain text files. THERE IS NO EXECUTABLE CODE contained within the library to infect - or for it to infect your system. Just to be sure I've just downloaded a copy, checked the contents is correct, then scanned it with windows defender and it's not showing any infections. To be doubly sure I've also uploaded it to an online virus scanner (virus total) which scans it though multiple anti-virus engines and that is also showing the files as completely clean.

It is very likely that your virus scanner is is showing a false positive.