⚠️⚠️⚠️ Библиотека архивирована! Используйте GyverDS3231 - она гораздо удобнее и имеет больше возможностей ⚠️⚠️⚠️

microDS3231

Лёгкая библиотека для работы с RTC DS3231 для Arduino

• Чтение и запись времени
• Вывод в char* и String
• Чтение температуры датчика

Совместимость

Совместима со всеми Arduino платформами (используются Arduino-функции)

Содержание

• Установка
• Инициализация
• Использование
• Пример
• Версии
• Баги и обратная связь

Установка

• Библиотеку можно найти по названию microDS3231 и установить через менеджер библиотек в:
  • Arduino IDE
  • Arduino IDE v2
  • PlatformIO
• Скачать библиотеку .zip архивом для ручной установки:
  • Распаковать и положить в C:\Program Files (x86)\Arduino\libraries (Windows x64)
  • Распаковать и положить в C:\Program Files\Arduino\libraries (Windows x32)
  • Распаковать и положить в Документы/Arduino/libraries/
  • (Arduino IDE) автоматическая установка из .zip: Скетч/Подключить библиотеку/Добавить .ZIP библиотеку… и указать скачанный архив
• Читай более подробную инструкцию по установке библиотек здесь

Обновление

• Рекомендую всегда обновлять библиотеку: в новых версиях исправляются ошибки и баги, а также проводится оптимизация и добавляются новые фичи
• Через менеджер библиотек IDE: найти библиотеку как при установке и нажать "Обновить"
• Вручную: удалить папку со старой версией, а затем положить на её место новую. "Замену" делать нельзя: иногда в новых версиях удаляются файлы, которые останутся при замене и могут привести к ошибкам!

Инициализация

MicroDS3231 rtc;        // адрес по умолчанию 0x68
MicroDS3231 rtc(адрес); // указать свой адрес

Использование

bool begin();                   // инициализация, вернет true, если RTC найден
void setTime(uint8_t param);    // установка времени == времени компиляции
void setTime(DateTime time);    // установить из структуры DateTime
void setTime(int8_t seconds, int8_t minutes, int8_t hours, int8_t date, int8_t month, int16_t year);	// установка времени
void setHMSDMY(int8_t hours, int8_t minutes, int8_t seconds, int8_t date, int8_t month, int16_t year);	// установка времени тип 2
    
// структура DateTime
uint8_t second; 
uint8_t minute;
uint8_t hour;
uint8_t day;    // день недели (пн.. вс = 1.. 7)
uint8_t date;
uint8_t month;
uint16_t year;

DateTime getTime();             // получить в структуру DateTime
uint8_t getSeconds();           // получить секунды
uint8_t getMinutes();           // получить минуты
uint8_t getHours();             // получить часы
uint8_t getDay();               // получить день недели
uint8_t getDate();              // получить число
uint16_t getYear();             // получить год
uint8_t getMonth();             // получить месяц
uint32_t getUnix(int16_t gmt);  // получить unix время (указать свой часовой пояс в часах ИЛИ минутах)

String getTimeString();         // получить время как строку вида HH:MM:SS
String getDateString();         // получить дату как строку вида DD.MM.YYYY
void getTimeChar(char* array);  // получить время как char array [8] вида HH:MM:SS
void getDateChar(char* array);  // получить дату как char array [10] вида DD.MM.YYYY       
    
bool lostPower();               // проверка на сброс питания
float getTemperatureFloat();    // получить температуру float
int getTemperature();           // получить температуру int

Пример

Остальные примеры смотри в examples!

// демо возможностей библиотеки
#include <microDS3231.h>
MicroDS3231 rtc;

void setup() {
  Serial.begin(9600);
  
  // проверка наличия модуля на линии i2c
  // вызов rtc.begin() не обязателен для работы
  if (!rtc.begin()) {
    Serial.println("DS3231 not found");
    for(;;);
  }
  
  // ======== УСТАНОВКА ВРЕМЕНИ АВТОМАТИЧЕСКИ ========
  // rtc.setTime(COMPILE_TIME);     // установить время == времени компиляции
  
  // визуально громоздкий, но более "лёгкий" с точки зрения памяти способ установить время компиляции
  rtc.setTime(BUILD_SEC, BUILD_MIN, BUILD_HOUR, BUILD_DAY, BUILD_MONTH, BUILD_YEAR);
    
  if (rtc.lostPower()) {            // выполнится при сбросе батарейки
    Serial.println("lost power!");
    // тут можно однократно установить время == времени компиляции
  }
  
  // ======== УСТАНОВКА ВРЕМЕНИ ВРУЧНУЮ ========    
  // установить время вручную можно двумя способами (подставить реальные числа)
  //rtc.setTime(SEC, MIN, HOUR, DAY, MONTH, YEAR);
  //rtc.setHMSDMY(HOUR, MIN, SEC, DAY, MONTH, YEAR);
  
  // также можно установить время через DateTime
  /*
  DateTime now;
  now.second = 0;
  now.minute = 10;
  now.hour = 50;
  now.date = 2;
  now.month = 9;
  now.year = 2021;
  
  rtc.setTime(now);  // загружаем в RTC
  */
}

void loop() {
  // получение и вывод каждой компоненты
  Serial.print(rtc.getHours());
  Serial.print(":");
  Serial.print(rtc.getMinutes());
  Serial.print(":");
  Serial.print(rtc.getSeconds());
  Serial.print(" ");
  Serial.print(rtc.getDay());
  Serial.print(" ");
  Serial.print(rtc.getDate());
  Serial.print("/");
  Serial.print(rtc.getMonth());
  Serial.print("/");
  Serial.println(rtc.getYear());
  
  /*
  // можно через DateTime (более оптимально):
  DateTime now = rtc.getTime();
  Serial.print(now.hour);
  Serial.print(":");
  Serial.print(now.minute);
  Serial.print(":");
  Serial.print(now.second);
  Serial.print(" ");
  Serial.print(now.day);
  Serial.print(" ");
  Serial.print(now.date);
  Serial.print("/");
  Serial.print(now.month);
  Serial.print("/");
  Serial.println(now.year);
  */
  
  // вывод температуры чипа
  Serial.println(rtc.getTemperatureFloat());  
  //Serial.println(rtc.getTemperature());
  
  // вывод времени готовой строкой String
  Serial.println(rtc.getTimeString());
  
  // вывод даты готовой строкой String
  Serial.println(rtc.getDateString());

  // вывод времени через char array
  char time[8];
  rtc.getTimeChar(time);
  Serial.println(time);
  
  // вывод даты через char array
  char date[10];
  rtc.getDateChar(date);
  Serial.println(date);
  
  Serial.println();
  delay(500);
}

Версии

• v1.2 - добавлены ограничения на вводимые в setTime числа. Также нельзя ввести 29 февраля увы =)
• v1.3 - пофикшено зависание, когда модуль отключен но опрашивается
• v1.4 - незначительный фикс
• v2.0 - новые возможности, оптимизация и облегчение
• v2.1 - добавил вывод температуры, вывод в String и char
• v2.2 - исправлены дни недели (пн-вс 1-7)
• v2.3 - небольшие исправления, оптимизация, изменён порядок вывода даты
• v2.4 - исправлена установка времени компиляции
• v2.5 - добавлен begin для проверки наличия модуля на линии
• v2.6 - исправлены отрицательные температуры
• v2.7 - добавлен вывод unix

Баги и обратная связь

При нахождении багов создавайте Issue, а лучше сразу пишите на почту [email protected]
Библиотека открыта для доработки и ваших Pull Request'ов!

При сообщении о багах или некорректной работе библиотеки нужно обязательно указывать:

• Версия библиотеки
• Какой используется МК
• Версия SDK (для ESP)
• Версия Arduino IDE
• Корректно ли работают ли встроенные примеры, в которых используются функции и конструкции, приводящие к багу в вашем коде
• Какой код загружался, какая работа от него ожидалась и как он работает в реальности
• В идеале приложить минимальный код, в котором наблюдается баг. Не полотно из тысячи строк, а минимальный код