PR1 review: Add STM32RTC library sources files

README.md

@@ -1,2 +1,53 @@
 # STM32RTC
 A RTC library for STM32.
+
+# API
+
+This library is based on the Arduino RTCZero library.
+The library allows to take control of the internal RTC of the STM32 boards.
+
+The following functions are not supported:
+
+* **`void standbyMode()`**: use the STM32 Low Power library instead.
+* **`uint8_t getAlarmMonth()`**: month not supported by STM32 RTC architecture.
+* **`uint8_t getAlarmYear()`**: year not supported by STM32 RTC architecture.
+* **`void setAlarmMonth(uint8_t month)`**: month not supported by STM32 RTC architecture.
+* **`void setAlarmYear(uint8_t year)`**: year not supported by STM32 RTC architecture.
+* **`void setAlarmDate(uint8_t day, uint8_t month, uint8_t year)`**: month and year not supported by STM32 RTC architecture.
+
+The following functions have been added to support specific STM32 RTC features:
+
+_RTC hours mode (12 or 24)_
+* **`void begin(RTC_Hour_Format format)`**
+
+_RTC clock source_
+* **`void setClockSource(RTC_Source_Clock source)`** : this function must be called before `begin()`.
+
+_RTC Asynchronous and Synchronous prescaler_
+* **`void getPrediv(int8_t *predivA, int16_t *predivS)`** : get user (a)synchronous prescaler values if set else computed ones for the current clock source.
+* **`void setPrediv(int8_t predivA, int16_t predivS)`** : set user (a)synchronous prescaler values.  This function must be called before `begin()`. Use -1 to reset value and use computed ones.
+
+_SubSeconds management_
+* **`uint32_t getSubSeconds(void)`**
+* **`void setSubSeconds(uint32_t subSeconds)`**
+
+_Hour format (AM or PM)_
+* **`uint8_t getHours(RTC_AM_PM *period)`**
+* **`void setHours(uint8_t hours, RTC_AM_PM period)`**
+* **`void setTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds, RTC_AM_PM period)`**
+* **`void setAlarmHours(uint8_t hours, RTC_AM_PM period)`**
+* **`uint8_t getAlarmHours(RTC_AM_PM *period)`**
+* **`void setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, RTC_AM_PM period)`**
+
+_Week day configuration_
+* **`uint8_t getWeekDay(void)`**
+* **`void setWeekDay(uint8_t weekDay)`**
+* **`void setDate(uint8_t weekDay, uint8_t day, uint8_t month, uint8_t year)`**
+
+Refer to the Arduino RTC documentation for the other functions  
+http://arduino.cc/en/Reference/RTC
+
+## Source
+
+Source files available at:  
+https://github.com/stm32duino/STM32RTC

examples/Epoch/Epoch.ino

@@ -0,0 +1,84 @@
+/**
+  ******************************************************************************
+  * @file    Epoch.ino
+  * @author  WI6LABS
+  * @version V1.0.0
+  * @date    12-December-2017
+  * @brief   RTC epoch example
+  *
+  ******************************************************************************
+  * @attention
+  *
+  * <h2><center>&copy; COPYRIGHT(c) 2017 STMicroelectronics</center></h2>
+  *
+  * Redistribution and use in source and binary forms, with or without modification,
+  * are permitted provided that the following conditions are met:
+  *   1. Redistributions of source code must retain the above copyright notice,
+  *      this list of conditions and the following disclaimer.
+  *   2. Redistributions in binary form must reproduce the above copyright notice,
+  *      this list of conditions and the following disclaimer in the documentation
+  *      and/or other materials provided with the distribution.
+  *   3. Neither the name of STMicroelectronics nor the names of its contributors
+  *      may be used to endorse or promote products derived from this software
+  *      without specific prior written permission.
+  *
+  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+  *
+  ******************************************************************************
+  */
+
+#include <STM32RTC.h>
+
+/* Create a rtc object */
+STM32RTC rtc;
+
+void setup() {
+  Serial.begin(9600);
+
+  rtc.begin(); // initialize RTC 24H format
+
+  rtc.setEpoch(1451606400); // Jan 1, 2016
+}
+
+void loop() {
+  Serial.print("Unix time = ");
+  Serial.println(rtc.getEpoch());
+
+  Serial.print("Seconds since Jan 1 2000 = ");
+  Serial.println(rtc.getY2kEpoch());
+
+  // Print date...
+  Serial.print(rtc.getDay());
+  Serial.print("/");
+  Serial.print(rtc.getMonth());
+  Serial.print("/");
+  Serial.print(rtc.getYear());
+  Serial.print("\t");
+
+  // ...and time
+  print2digits(rtc.getHours());
+  Serial.print(":");
+  print2digits(rtc.getMinutes());
+  Serial.print(":");
+  print2digits(rtc.getSeconds());
+
+  Serial.println();
+
+  delay(1000);
+}
+
+void print2digits(int number) {
+  if (number < 10) {
+    Serial.print("0");
+  }
+  Serial.print(number);
+}

examples/RTCClockSelection/RTCClockSelection.ino

@@ -0,0 +1,112 @@
+/**
+  ******************************************************************************
+  * @file    RTCClockSelection.ino
+  * @author  WI6LABS
+  * @version V1.0.0
+  * @date    15-March-2018
+  * @brief   RTC clock selection: LSI, LSE or HSE. Refer to board datasheet to
+  *          know available clock.
+  *
+  ******************************************************************************
+  * @attention
+  *
+  * <h2><center>&copy; COPYRIGHT(c) 2018 STMicroelectronics</center></h2>
+  *
+  * Redistribution and use in source and binary forms, with or without modification,
+  * are permitted provided that the following conditions are met:
+  *   1. Redistributions of source code must retain the above copyright notice,
+  *      this list of conditions and the following disclaimer.
+  *   2. Redistributions in binary form must reproduce the above copyright notice,
+  *      this list of conditions and the following disclaimer in the documentation
+  *      and/or other materials provided with the distribution.
+  *   3. Neither the name of STMicroelectronics nor the names of its contributors
+  *      may be used to endorse or promote products derived from this software
+  *      without specific prior written permission.
+  *
+  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+  *
+  ******************************************************************************
+  */
+
+#include <STM32RTC.h>
+
+/* Create a rtc object */
+STM32RTC rtc;
+
+/* Change these values to set the current initial time */
+const byte seconds = 0;
+const byte minutes = 0;
+const byte hours = 16;
+
+/* Change these values to set the current initial date */
+/* Monday 15th June 2015 */
+const byte weekDay = 1;
+const byte day = 15;
+const byte month = 6;
+const byte year = 15;
+
+void setup()
+{
+  Serial.begin(9600);
+
+  // Select RTC clock source: RTC_LSI_CLOCK, RTC_LSE_CLOCK or RTC_HSE_CLOCK.
+  // By default the LSI is selected as source.
+  rtc.setClockSource(STM32RTC::RTC_LSE_CLOCK);
+
+  rtc.begin(); // initialize RTC 24H format
+
+  // Set the time
+  rtc.setHours(hours);
+  rtc.setMinutes(minutes);
+  rtc.setSeconds(seconds);
+
+  // Set the date
+  rtc.setWeekDay(weekDay);
+  rtc.setDay(day);
+  rtc.setMonth(month);
+  rtc.setYear(year);
+
+  // you can use also
+  //rtc.setTime(hours, minutes, seconds);
+  //rtc.setDate(weekDay, day, month, year);
+}
+
+void loop()
+{
+  // Print date...
+  print2digits(rtc.getDay());
+  Serial.print("/");
+  print2digits(rtc.getMonth());
+  Serial.print("/");
+  print2digits(rtc.getYear());
+  Serial.print(" ");
+
+  // ...and time
+  print2digits(rtc.getHours());
+  Serial.print(":");
+  print2digits(rtc.getMinutes());
+  Serial.print(":");
+  print2digits(rtc.getSeconds());
+
+  Serial.println();
+
+  delay(1000);
+}
+
+
+
+void print2digits(int number) {
+  if (number < 10) {
+    Serial.print("0"); // print a 0 before if the number is < than 10
+  }
+  Serial.print(number);
+}

examples/SimpleRTC/SimpleRTC.ino

@@ -0,0 +1,107 @@
+/**
+  ******************************************************************************
+  * @file    SimpleRTC.ino
+  * @author  WI6LABS
+  * @version V1.0.0
+  * @date    12-December-2017
+  * @brief   Simple RTC example.
+  *
+  ******************************************************************************
+  * @attention
+  *
+  * <h2><center>&copy; COPYRIGHT(c) 2017 STMicroelectronics</center></h2>
+  *
+  * Redistribution and use in source and binary forms, with or without modification,
+  * are permitted provided that the following conditions are met:
+  *   1. Redistributions of source code must retain the above copyright notice,
+  *      this list of conditions and the following disclaimer.
+  *   2. Redistributions in binary form must reproduce the above copyright notice,
+  *      this list of conditions and the following disclaimer in the documentation
+  *      and/or other materials provided with the distribution.
+  *   3. Neither the name of STMicroelectronics nor the names of its contributors
+  *      may be used to endorse or promote products derived from this software
+  *      without specific prior written permission.
+  *
+  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+  *
+  ******************************************************************************
+  */
+
+#include <STM32RTC.h>
+
+/* Create a rtc object */
+STM32RTC rtc;
+
+/* Change these values to set the current initial time */
+const byte seconds = 0;
+const byte minutes = 0;
+const byte hours = 16;
+
+/* Change these values to set the current initial date */
+/* Monday 15th June 2015 */
+const byte weekDay = 1;
+const byte day = 15;
+const byte month = 6;
+const byte year = 15;
+
+void setup()
+{
+  Serial.begin(9600);
+
+  rtc.begin(); // initialize RTC 24H format
+
+  // Set the time
+  rtc.setHours(hours);
+  rtc.setMinutes(minutes);
+  rtc.setSeconds(seconds);
+
+  // Set the date
+  rtc.setWeekDay(weekDay);
+  rtc.setDay(day);
+  rtc.setMonth(month);
+  rtc.setYear(year);
+
+  // you can use also
+  //rtc.setTime(hours, minutes, seconds);
+  //rtc.setDate(weekDay, day, month, year);
+}
+
+void loop()
+{
+  // Print date...
+  print2digits(rtc.getDay());
+  Serial.print("/");
+  print2digits(rtc.getMonth());
+  Serial.print("/");
+  print2digits(rtc.getYear());
+  Serial.print(" ");
+
+  // ...and time
+  print2digits(rtc.getHours());
+  Serial.print(":");
+  print2digits(rtc.getMinutes());
+  Serial.print(":");
+  print2digits(rtc.getSeconds());
+
+  Serial.println();
+
+  delay(1000);
+}
+
+
+
+void print2digits(int number) {
+  if (number < 10) {
+    Serial.print("0"); // print a 0 before if the number is < than 10
+  }
+  Serial.print(number);
+}