Skip to content
This repository was archived by the owner on Feb 28, 2024. It is now read-only.

Commit d5eb5cf

Browse files
committed
RTC: Added javadoc comments
1 parent b64da1d commit d5eb5cf

File tree

1 file changed

+142
-3
lines changed

1 file changed

+142
-3
lines changed

src/utility/RTC/PCF8563T.cpp

Lines changed: 142 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
#define PCF8563T_MONTHS_REG 0x07
2929
#define PCF8563T_YEARS_REG 0x08
3030

31-
// allarm management
31+
// allarm managemet
3232
#define PCF8563T_MINUTE_ALARM_REG 0x09
3333
#define PCF8563T_MINUTE_ALARM_AE_M_MASK 0x80
3434
#define PCF8563T_MINUTE_ALARM_ON 0x7F
@@ -49,10 +49,20 @@
4949
#define PCF8563T_STATUS_2_CLEAR_INT 0xF7
5050
#define PCF8563T_STATUS_2_INT_OFF 0x7d
5151

52+
/**
53+
* Object constructor
54+
*
55+
*/
5256
PCF8563TClass::PCF8563TClass()
5357
{
5458
}
5559

60+
/**
61+
* Start the communication with the RTC
62+
* Initialize I2C (Wire1) bus and check if the chip is connected trhoug sending an ACK on the I2C bus.
63+
* @return true if the RTC Controller is on the I2C bus, false if it is not.
64+
*
65+
*/
5666
bool PCF8563TClass::begin()
5767
{
5868
Wire1.begin(); // join i2c bus
@@ -64,12 +74,22 @@ bool PCF8563TClass::begin()
6474
return false;
6575
}
6676

77+
/**
78+
* Set Year number's value
79+
* Save an unsigned byte with the Year's value
80+
* @param years Year's unsigned byte
81+
*/
6782
void PCF8563TClass::setYears(uint8_t years) {
6883
uint8_t dec = years / 10;
6984
uint8_t unit = years - (dec * 10);
7085
writeByte(PCF8563T_YEARS_REG, ((dec << 4) + unit));
7186
}
7287

88+
/**
89+
* Set Month number's value
90+
* Save an unsigned byte with the Month's value
91+
* @param months Month's unsigned byte (0 to 12)
92+
*/
7393
void PCF8563TClass::setMonths(uint8_t months) {
7494
uint8_t offset = 0;
7595
if (months > 9) {
@@ -78,35 +98,65 @@ void PCF8563TClass::setMonths(uint8_t months) {
7898
writeByte(PCF8563T_MONTHS_REG, months + offset);
7999
}
80100

101+
/**
102+
* Set Day number's value
103+
* Save an unsigned byte with the Day's value
104+
* @param days day's unsigned byte
105+
*/
81106
void PCF8563TClass::setDays(uint8_t days) {
82107
uint8_t dec = days / 10;
83108
uint8_t unit = days - (dec * 10);
84109
writeByte(PCF8563T_DAYS_REG, ((dec << 4) + unit));
85110
}
86111

112+
/**
113+
* Set Hour(s) number's value
114+
* Save an unsigned byte with the Hour(s) value
115+
* @param hours hour unsigned byte (0 - 23)
116+
*/
87117
void PCF8563TClass::setHours(uint8_t hours) {
88118
uint8_t dec = hours / 10;
89119
uint8_t unit = hours - (dec * 10);
90120
writeByte(PCF8563T_HOURS_REG, ((dec << 4) + unit)); //check formula on datasheet val + 6 * (val / 10)
91121
}
92122

123+
/**
124+
* Set Minute(s) number's value
125+
* Save an unsigned byte with the Minute(s) value
126+
* @param minutes minute unsigned byte (0-60)
127+
*/
93128
void PCF8563TClass::setMinutes(uint8_t minutes) {
94129
uint8_t dec = minutes / 10;
95130
uint8_t unit = minutes - (dec * 10);
96131
writeByte(PCF8563T_MINUTES_REG, ((dec << 4) + unit));
97132
}
98133

134+
/**
135+
* Set Second(s) number's value
136+
* Save an unsigned byte with the Second(s) value
137+
* @param seconds Second(s) unsigned byte (0-60)
138+
*/
99139
void PCF8563TClass::setSeconds(uint8_t seconds) {
100140
uint8_t dec = seconds / 10;
101141
uint8_t unit = seconds - (dec * 10);
102142
writeByte(PCF8563T_VL_SECONDS_REG, ((dec << 4) + unit));
103143
}
104144

145+
/**
146+
* Get Year(s) number's value
147+
* Get unsigned byte with the Year(s) value
148+
* @return byte with Year(s) value
149+
*/
105150
uint8_t PCF8563TClass::getYears() {
106151
uint8_t years = readByte(PCF8563T_YEARS_REG);
107152
return (years & 0x0F) + ((years >> 4)*10);
108153
}
109154

155+
/**
156+
* Get Month(s) month's value
157+
* Get unsigned byte with the month(s) value
158+
* @return byte with Month(s) value
159+
*/
110160
uint8_t PCF8563TClass::getMonths() {
111161
uint8_t months = readByte(PCF8563T_MONTHS_REG) & 0x1F;
112162
if(months > 9) {
@@ -116,27 +166,50 @@ uint8_t PCF8563TClass::getMonths() {
116166
}
117167
}
118168

169+
/**
170+
* Get Day(s) number's value
171+
* Get unsigned byte with the Day(s) value
172+
* @return byte with Day(s) value
173+
*/
119174
uint8_t PCF8563TClass::getDays() {
120175
uint8_t days = readByte(PCF8563T_DAYS_REG);
121176
return (days & 0x0F) + ((days >> 4)*10);
122177
}
123178

179+
/**
180+
* Get Hour(s) number's value
181+
* Get unsigned byte with the Hour(s) value
182+
* @return byte with Hour(s) value
183+
*/
124184
uint8_t PCF8563TClass::getHours() {
125185
uint8_t hours = readByte(PCF8563T_HOURS_REG) & 0x3F;
126186
return (hours & 0x0F) + ((hours >> 4)*10);
127187
}
128188

189+
/**
190+
* Get Minute(s) number's value
191+
* Get unsigned byte with the Minute(s) value
192+
* @return byte with Minute(s) value
193+
*/
129194
uint8_t PCF8563TClass::getMinutes() {
130195
uint8_t minutes = (readByte(PCF8563T_MINUTES_REG)) & 0x7F ;
131196
return (minutes & 0x0F) + ((minutes >> 4)*10);
132197
}
133198

199+
/**
200+
* Get Second(s) number's value
201+
* Get unsigned byte with the Second(s) value
202+
* @return byte with Second(s) value
203+
*/
134204
uint8_t PCF8563TClass::getSeconds() {
135205
uint8_t seconds = readByte(PCF8563T_VL_SECONDS_REG) & 0x7F;
136206
return (seconds & 0x0F) + ((seconds >> 4)*10);
137207
}
138208

139-
209+
/**
210+
* Set time Epoch format
211+
*
212+
*/
140213
void PCF8563TClass::setEpoch() {
141214
struct tm time;
142215
time.tm_sec = getSeconds();
@@ -150,6 +223,12 @@ void PCF8563TClass::setEpoch() {
150223
set_time(seconds);
151224
}
152225

226+
/**
227+
* Set time with Epoch format
228+
*
229+
*
230+
* @param seconds number of seconds (time_t type)
231+
*/
153232
void PCF8563TClass::setEpoch(time_t seconds) {
154233
struct tm time;
155234
_rtc_localtime(seconds, &time, RTC_FULL_LEAP_YEAR_SUPPORT);
@@ -163,7 +242,19 @@ void PCF8563TClass::setEpoch(time_t seconds) {
163242
set_time(seconds);
164243
}
165244

166-
245+
/**
246+
* Set time with Epoch format
247+
*
248+
* Convert the input values to Epoch format
249+
* example: Tue, 06 Jul 2021 11:55:27 GMT -> 1625572527
250+
*
251+
* @param years number of years
252+
* @param mohths number of months
253+
* @param days number of days
254+
* @param hours number of hours
255+
* @param minutes number of minutes
256+
* @param seconds number of seconds
257+
*/
167258
void PCF8563TClass::setEpoch(uint8_t years, uint8_t months, uint8_t days, uint8_t hours, uint8_t minutes, uint8_t seconds) {
168259
struct tm time;
169260
time_t utcsec;
@@ -179,6 +270,15 @@ void PCF8563TClass::setEpoch(uint8_t years, uint8_t months, uint8_t days, uint8_
179270
set_time(utcsec);
180271
}
181272

273+
/**
274+
* Get epoch number
275+
* Convert real time to difference between actual time and Epoch(Unix time)
276+
* Saved into time_t type
277+
*
278+
* example: 1625572527 -> Tue, 06 Jul 2021 11:55:27 GMT
279+
*
280+
* @return number of seconds after Unix time (time_t type)
281+
*/
182282
time_t PCF8563TClass::getEpoch() {
183283
struct tm time;
184284
time_t seconds;
@@ -194,47 +294,86 @@ time_t PCF8563TClass::getEpoch() {
194294
return seconds;
195295
}
196296

297+
/**
298+
* Enable alarm
299+
*
300+
*/
197301
void PCF8563TClass::enableAlarm() {
198302
writeByte(PCF8563T_STATUS_2_REG, (readByte(PCF8563T_STATUS_2_REG) & PCF8563T_STATUS_2_CLEAR_INT) | PCF8563T_STATUS_2_AIE_MASK);
199303
}
200304

305+
/**
306+
* Disable alarm
307+
*
308+
*/
201309
void PCF8563TClass::disableAlarm() {
202310
writeByte(PCF8563T_STATUS_2_REG, (readByte(PCF8563T_STATUS_2_REG) & PCF8563T_STATUS_2_INT_OFF));
203311
}
204312

313+
/**
314+
* Clear alarm status
315+
*
316+
*/
205317
void PCF8563TClass::clearAlarm() {
206318
writeByte(PCF8563T_STATUS_2_REG, (readByte(PCF8563T_STATUS_2_REG) & PCF8563T_STATUS_2_CLEAR_INT) | PCF8563T_STATUS_2_AIE_MASK);
207319
}
208320

321+
/**
322+
* Set alarm's minute
323+
*
324+
* @param minutes minute(s) value for the Alarm (byte type)
325+
*/
209326
void PCF8563TClass::setMinuteAlarm(uint8_t minutes) {
210327
uint8_t dec = minutes / 10;
211328
uint8_t unit = minutes - (dec * 10);
212329
uint8_t min_alarm = PCF8563T_MINUTE_ALARM_ON & ((dec << 4) + unit);
213330
writeByte(PCF8563T_MINUTE_ALARM_REG , min_alarm);
214331
}
215332

333+
/**
334+
* Disable and clear the minute of the Alarm
335+
*
336+
*/
216337
void PCF8563TClass::disableMinuteAlarm() {
217338
writeByte(PCF8563T_MINUTE_ALARM_REG, readByte(PCF8563T_MINUTE_ALARM_REG) | PCF8563T_MINUTE_ALARM_AE_M_MASK);
218339
}
219340

341+
/**
342+
* Set Alarm's hour
343+
*
344+
* @param hours hour(s) value for the Alarm (byte type)
345+
*/
220346
void PCF8563TClass::setHourAlarm(uint8_t hours) {
221347
uint8_t dec = hours / 10;
222348
uint8_t unit = hours - (dec * 10);
223349
uint8_t hour_alarm = PCF8563T_HOUR_ALARM_AE_H_MASK & ((dec << 4) + unit);
224350
writeByte(PCF8563T_HOURS_REG, hour_alarm); //check formula on datasheet val + 6 * (val / 10)
225351
}
226352

353+
/**
354+
* Disable and clear the hour of the Alarm
355+
*
356+
*/
227357
void PCF8563TClass::disableHourAlarm() {
228358
writeByte(PCF8563T_HOUR_ALARM_REG, readByte(PCF8563T_HOUR_ALARM_REG) | PCF8563T_HOUR_ALARM_AE_H_MASK);
229359
}
230360

361+
/**
362+
* Set Alarm's day
363+
*
364+
* @param days day value for the Alarm (byte type)
365+
*/
231366
void PCF8563TClass::setDayAlarm(uint8_t days) {
232367
uint8_t dec = days / 10;
233368
uint8_t unit = days - (dec * 10);
234369
uint8_t day_alarm = PCF8563T_DAY_ALARM_ON & ((dec << 4) + unit);
235370
writeByte(PCF8563T_DAY_ALARM_REG, day_alarm);
236371
}
237372

373+
/**
374+
* Disable and clear the day of the Alarm
375+
*
376+
*/
238377
void PCF8563TClass::disableDayAlarm() {
239378
writeByte(PCF8563T_DAY_ALARM_REG, readByte(PCF8563T_DAY_ALARM_REG) | PCF8563T_DAY_ALARM_AE_D_MASK );
240379
}

0 commit comments

Comments
 (0)