Skip to content

Commit

Permalink
add error to text function
Browse files Browse the repository at this point in the history 
tidy readme
fix manifest
  • Loading branch information
CDFER committed Jun 15, 2023
1 parent 9673f74 commit 9f54feb
Show file tree
Hide file tree
Showing 4 changed files with 76 additions and 73 deletions.
77 changes: 19 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,31 @@
Sure! Here's an improved version of the README file with a markdown table showcasing the functions in the library:

---

# pcf8563-RTC

A library to interface ESP chips with the NXP PCF8563 Real-Time Clock (RTC) in the Arduino (C++) Framework.
The `pcf8563-RTC` library is designed to interface ESP chips with the NXP PCF8563 Real-Time Clock (RTC) within the Arduino (C++) Framework.

## Features

- Supports multiple I2C buses -> `rtc.begin(Wire1);`
- Works with timezones (RTC is set to UTC)
- Supports multiple I2C buses: `rtc.begin(Wire1);`
- Timezone support (RTC is set to UTC)
- [List of timezones](https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv)
- Sets System (ESP32) time from RTC (assumes RTC is set to UTC/GMT)
- Sets RTC time from System (epoch)
- Set RTC time using WiFi example
- Sets the system (ESP32) time from the RTC (assumes RTC is set to UTC/GMT)
- Sets the RTC time from the system (epoch)
- Example of setting RTC time using WiFi

## Warnings

- Not all functions are implemented
- Not compatible with Lewis' library
- Only tested with the ESP32
- Under development
- Only tested with the ESP32 and S2 variants
- Currently under development

## Setup
## Example ESP32 Code

```c++
```cpp
#include "pcf8563.h"
#include "time.h"

PCF8563_Class rtc;
const char *time_zone = "NZST-12NZDT,M9.5.0,M4.1.0/3"; // [List of timezones](https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv)
const char *time_zone = "NZST-12NZDT,M9.5.0,M4.1.0/3"; // [List of timezones](https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv)

Wire.begin();
rtc.begin(Wire);
Expand All @@ -38,9 +34,7 @@ tzset();
rtc.syncToSystem();
```
## Loop
```c++
```cpp
struct tm timeinfo;
getLocalTime(&timeinfo);
Serial.print(&timeinfo, "%d/%m/%y %H:%M:%S");
Expand All @@ -51,56 +45,23 @@ Serial.print(&timeinfo, "%d/%m/%y %H:%M:%S");
![Schematic](/images/schematic.png)

- Uses a CR1220 coincell (though almost any 3V lithium coincell should work)
- To not discharge the battery too fast, disable output clock and alarms
- Low backup current: typical 0.25uA at 3.0V (theoretical, not tested)
- To prevent battery discharge, disable output clock and alarms
- Low backup current: typically 0.25uA at 3.0V (theoretical, not tested)
- Currently testing with 4.7kohm pull-ups on SDA and SCL
- Currently using a Seiko Epson Q13FC1350000400 crystal (+-20ppm)
- In theory, this setup will drift by a maximum of ~11 minutes per year ([Real-Time Clock Calculator](https://www.analog.com/en/design-center/interactive-design-tools/real-time-clock-calculator.html))
- In theory, a 37mAh CR1220 battery will last ~14 years without any charging (including battery self-discharge)
- 3.3V -> diode -> resistor charging of a coincell from 3.3V is hotly debated as to whether it is a good, okay, or horrifically bad idea. I have not had any issues, but your mileage may vary
- Be careful with PCB placement (have the crystal as close to the RTC chip as possible and surround it with ground planes connected with vias)
- Charging a coincell from 3.3V through a diode and resistor is a topic of debate. It is important to exercise caution and consider individual circumstances. Using a 200-ohm resistor should limit the current to a maximum of 12mA, while a 1k-ohm resistor should limit it to a maximum of 2.6mA.
- Be careful with PCB placement; ensure the crystal is placed as close to the RTC chip as possible and surrounded by ground planes connected with vias

## Based on the awesome work of Lewis He
## Acknowledgments

Originally created by Lewis He in 2019
This library is based on the original work of Lewis He, created in 2019.

[GitHub Repository](https://github.com/lewisxhe/PCF8563_Library)

## License

This library is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.

---

And here's the markdown table with the functions:

| Function | Description |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `int begin(TwoWire &port = Wire, uint8_t addr = PCF8563_ADDRESS)` | Initializes the PCF8563 RTC. |
| `void setDateTime(uint16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second)` | Sets the date and time on the RTC. |
| `void setDateTime(RTC_Date date)` | Sets the date and time on the RTC using an RTC_Date object. |
| `RTC_Date getDateTime()` | Retrieves the current date and time from the RTC. |
| `RTC_Alarm getAlarm()` | Retrieves the alarm settings from the RTC. |
| `void enableAlarm()` | Enables the alarm on the RTC. |
| `void disableAlarm()` | Disables the alarm on the RTC. |
| `bool alarmActive()` | Checks if the alarm is active on the RTC. |
| `void resetAlarm()` | Resets the alarm on the RTC. |
| `void setAlarm(RTC_Alarm alarm)` | Sets the alarm on the RTC using an RTC_Alarm object. |
| `void setAlarm(uint8_t hour, uint8_t minute, uint8_t day, uint8_t weekday)` | Sets the alarm on the RTC using individual values for hour, minute, day, and weekday. |
| `bool isValid()` | Checks if the clock data on the RTC can be trusted. |
| `void setAlarmByWeekDay(uint8_t weekday)` | Sets the alarm on the RTC based on the weekday. |
| `void setAlarmByHours(uint8_t hour)` | Sets the alarm on the RTC based on the hour. |
| `void setAlarmByDays(uint8_t day)` | Sets the alarm on the RTC based on the day. |
| `void setAlarmByMinutes(uint8_t minute)` | Sets the alarm on the RTC based on the minute. |
| `bool isTimerEnable()` | Checks if the timer is enabled on the RTC. |
| `bool isTimerActive()` | Checks if the timer is active on the RTC. |
| `void enableTimer()` | Enables the timer on the RTC. |
| `void disableTimer()` | Disables the timer on the RTC. |
| `void setTimer(uint8_t val, uint8_t freq, bool enInterrupt)` | Sets the timer on the RTC with the specified values. |
| `void clearTimer()` | Clears the timer on the RTC. |
| `bool enableCLK(uint8_t freq)` | Enables the clock output on the RTC with the specified frequency. |
| `void disableCLK()` | Disables the clock output on the RTC. |
| `bool syncToSystem()` | Sets the system time from the RTC if the RTC data is valid. |
| `bool syncToRtc()` | Sets the RTC time from the system time (ESP) if the system time is between 1970 and 2100. |

Please note that not all functions are implemented, and the library is under active development. Make sure to refer to the documentation and examples for more information on how to use the library.
Please note that not all functions are implemented, and the library is under active development. For more information on how to use the library, refer to the documentation and examples provided.
27 changes: 12 additions & 15 deletions library.json
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,25 @@
{
"name": "pcf8563-rtc",
"version": "1.2.0",
"description": "An Arduino library for interfacing ESP chips with PCF8563 Real Time Clock using the I2C protocol.",
"keywords": [
"rtc",
"clock"
"clock",
"pcf8563",
"nxt",
"i2c"
],
"description": "A library for the PCF8563",
"repository": {
"type": "git",
"url": "https://github.com/CDFER/pcf8563-RTC.git"
},
"frameworks": "arduino",
"platforms": {
"espressif32": {}
"author": {
"name": "Chris Dirks",
"url": "https://keastudios.co.nz/about.htm",
"maintainer": true
},
"license": "Other",
"homepage": "https://github.com/CDFER/pcf8563-RTC",
"license": "MIT",
"authors": [
{
"name": "Your Name",
"email": "your-email@example.com"
}
],
"bugs": {
"url": "https://github.com/CDFER/pcf8563-RTC/issues"
}
"frameworks": "arduino",
"platforms": "*"
}
23 changes: 23 additions & 0 deletions pcf8563.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,29 @@ uint8_t PCF8563_Class::begin(TwoWire &port, int addr) {
return _i2cPort->endTransmission(); // Check if the transmission was successful and return the result
}

const char *PCF8563_Class::getErrorText(uint8_t errorCode) {
switch (errorCode) {
case 0:
return "Success";
case 1:
return "I2C data too long to fit in transmit buffer";
case 2:
return "I2C received NACK on transmit of address";
case 3:
return "I2C received NACK on transmit of data";
case 4:
return "I2C other error";
case 5:
return "I2C timeout";
case 6:
return "bytesReceived(%i) != bytesRequested(%i)";
case 7:
return "Measurement out of range";
default:
return "Unknown error";
}
}

void PCF8563_Class::setDateTime(RTC_Date date) {
setDateTime(date.year, date.month, date.day, date.hour, date.minute, date.second);
// Call the setDateTime function with individual date and time components
Expand Down
22 changes: 22 additions & 0 deletions pcf8563.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,28 @@ class PCF8563_Class {
*/
uint8_t begin(TwoWire &port = Wire, int addr = PCF8563_ADDRESS);

/**
* @brief Converts an error code into descriptive text.
*
* This function takes an error code and returns a corresponding descriptive text. It can be used to convert
* error codes returned by the RTC into human-readable error messages.
*
* @param errorCode The error code to convert.
* @return A pointer to a constant character array containing the descriptive text of the error.
* If the error code is not recognized, "Unknown error" is returned.
*
* @note The error codes and their meanings are as follows:
* - 0: Success
* - 1: I2C data too long to fit in transmit buffer
* - 2: I2C received NACK on transmit of address
* - 3: I2C received NACK on transmit of data
* - 4: I2C other error
* - 5: I2C timeout
* - 6: bytesReceived(%i) != bytesRequested(%i)
* - 7: Measurement out of range
*/
const char *getErrorText(uint8_t errorCode);

/**
* @brief Sets the date and time of the RTC.
* @param year The year.
Expand Down

0 comments on commit 9f54feb

Please sign in to comment.