Библиотека DS1307

DS1307

описание библиотеки для использования в Arduino модуля реального времени DS3107 на русском языке

Скачать:   на официальном сайте       зеркало1    зеркало2

Введение: 

   Эта библиотека была написана для легкого взаимодействия и использования модуля на микросхеме DS1307 с Arduino или chipKit без необходимости использования библиотеки Wire.
   Данная библиотека использует по умолчанию режим Fast Mode (400 кГц) аппаратного интерфейса I2C.
    Работа этой библиотека не гарантируется в режиме одновременной работы с библиотекой Wire и совместного использования контактов. 

Структура:

Time;
Структура управления данными времени и даты.
Переменные: 
hour, min, sec: Для определения данных времени
date, mon, year: Для определения данных даты
dow: День недели, начиная с понедельника
Пример: Time t; // Определяем структуру с именем t класса "время"

DS1307_RAM;
Буфер для использования совместно с ReadBuffer () и WriteBuffer ().
Переменные: 
Cell [0-56]: Байт-массив для хранения данных, с возможностью чтения или записи в ОЗУ микросхемы.
Пример: DS1307_RAM ramBuffer; // Объявляем буфер для использования

Определенные литералы:

Дни недели
Используется совместно с setDOW() и Time.dow
MONDAY:          1
TUESDAY:         2
WEDNESDAY:  3
THURSDAY:      4
FRIDAY:             5
SATURDAY:      6
SUNDAY:           7

Длина названия
Используется совместно с getTimeStr(), getDateStr(), getDOWStr() and getMonthStr()
FORMAT_SHORT: 1 (полное название)
FORMAT_LONG:  2 (сокращенное (3 буквенное) название)


Формат даты
Используется совместно с getDateStr()
FORMAT_LITTLEENDIAN:    1  (дд.мм.гггг)
FORMAT_BIGENDIAN:          2  (гггг.мм.дд)
FORMAT_MIDDLEENDIAN:  3  (мм.дд.гггг)

Частота на выходе SQW

Используется совместно с setSQWRate()

SQW_RATE_1:     1  (1 Гц)

SQW_RATE_4K:  2  (4096 Гц)

SQW_RATE_8K:  3  (8192 Гц)

SQW_RATE_32K:  4  (32768 Гц)

Функции:

DS1307(SDA, SCL);
Инициализация библиотеки с помощью интерфейса I2C
Параметры:
SDA: Вывод подключения SDA-пина DS1307 (Вывод 5, данные)
SCL: Вывод подключения SCL-пина DS1307 (вывод 6, тактирование)
Пример: DS1307 rtc(SDA, SCL); // Инициализация библиотеки DS13071 с помощью  интерфейса I2C
Примечание: DS1307 можно подключать с любым свободным выводам Arduino. Если в схеме уже используется шина I2C и Вы попытаетесь подключиться к тем же выводам, то данная библиотека работать не будет, т.к. любой TWI-совместимый протокол требует исключительного доступа к пинам.

begin();
Инициализация подключения к DS1307
Параметры: Нет
Возврат: Нет

Пример:  rtc.begin(); //Инициализация подключения к DS1307

getTime();
Считать текущие данные из DS3231.
Параметры: Нет
Возврат: формат Time-structure
Пример: t = rtc.getTime(); // Считать текущую дату и время.

getTimeStr([format]);
Считать текущее время в виде строковой переменной.
Параметры:
format: <необязательный параметр>
     FORMAT_LONG "ЧЧ:ММ:СС" (По умолчанию)
     FORMAT_SHORT "ЧЧ:ММ"
Возврат: Строковое значение, содержащее текущее время с секундами или без них.
Пример: Serial.print(rtc.getTimeStr()); // Отправить текущее время через последовательный порт


getDateStr([slformat[, eformat[, divider]]]);
Считать текущую дату в виде строковой переменной.
Параметры: 
slformat: <необязательный параметр>
     FORMAT_LONG Год из 4х цифр (ГГГГ) (По умолчанию)
     FORMAT_SHORT Год из 2х цифр (ГГ)
eformat: <необязательный параметр>
     FORMAT_LITTLEENDIAN "ДД.ММ.ГГГГ" (По умолчанию)
     FORMAT_BIGENDIAN "ГГГГ.ММ.ДД"
     FORMAT_MIDDLEENDIAN "ММ.ДД.ГГГГ"
divider: <необязательный параметр>
Символ для разделения. По умолчанию '.'
Возврат: Строковое значение, содержащее текущую дату в указанном формате.
Пример: Serial.print(rtc.getDateStr()); // Отправить текущую дату через последовательный порт (В формате "ДД.ММ.ГГГГ")

getDOWStr([format]);
Считать текущий день недели в виде строковой переменной.
Параметры:
format: <необязательный параметр>
     FORMAT_LONG День недели на английском языке (По умолчанию)
     FORMAT_SHORT Сокращенное название дня недели на английском языке (3 символа)
Возврат: Строковое значение, содержащее текущий день день недели в полном или сокращенном формате.
Пример: Serial.print(rtc.getDOWStr(FORMAT_SHORT)); // Отправить сокращенное название текущего дня недели через последовательный порт

getMonthStr([format]);
Считать текущий месяц в виде строковой переменной.
Параметры: 
format: <необязательный параметр>
     FORMAT_LONG название месяца на английском языке (По умолчанию)
     FORMAT_SHORT Сокращенное название месяца на английском языке (3 символа)
Возврат: Строковое значение, содержащее текущий месяц в полном или сокращенном формате.
Пример: Serial.print(rtc.getMonthStr()); // Отправить название текущего месяца через последовательный порт

getUnixTime(time);
Преобразование значения времени и даты в формат Unix Time (UNIX-время).
Параметры: 
Время: Переменная, содержащее дату и время для преобразования
Возврат: Unix Time для предоставленного значения времени
Пример: Serial.print(rtc.getUnixTime(rtc.getTime())); // Отправить текущее значение Unixtime через последовательный порт
Примечание: UNIX-время (англ. Unix time) или POSIX-время — система описания моментов во времени, принятая в UNIX и других POSIX-совместимых операционных системах. Определяется как количество секунд, прошедших с полуночи (00:00:00 UTC) 1 января 1970 года (четверг); время с этого момента называют «эрой UNIX» (англ. Unix Epoch).

setTime(hour, min, sec);
Установка времени.
Параметры:
hour: Часы (0-23)
min: Минуты (0-59)
sec: Секунды (0-59)
Пример: rtc.setTime(23, 59, 59); // Установка времени 23:59:59

setDate(date, mon, year);
Установка даты.
Параметры:
date: День (1-31)
mon:  Месяц (1-12)
year: Год (2000-2099)
Пример: rtc.setDate(16, 5, 2016); // Установка даты 16 мая 2016г.
Примечание: Защиты от ввода неправильной даты нет. Т.е., возможно ввести 31 февраля, но результат будет не предсказуем

setDOW(dow);
Установка дня недели.
Параметры: 
dow:  <необязательный параметр> День недели (1-7)
Если параметр не задан, значение параметра будет рассчитываться на основе данных, хранящихся в настоящее время в DS3231.
Пример: rtc.setDOW(FRIDAY); // Установить день недели - Пятница
Примечание: Устанавливаются от понедельника (1) до воскресенья (7).

halt(value);
Установка или сброс флага запуска часов.
Параметры: 
value: true: Установить CH флаг
            false: Сбросить  CH флаг
Возврат: Нет
Пример: rtc.halt(false); // Запустить часовой модуль в работу

setOutput(enable);
Установка на выводе SQW/OUT (вывод 7) микросхемы DS1307 высокого или низкого уровня. Данная команда не работает, если enableSQW() имеет значение TRUE.
Параметры: 
enable: TRUE: Установить на выводе высокий уровень
                FALSE: Установить на выводе низкий уровень.
Возврат: Нет
Пример: rtc.setOutput(true); // Установить на выводе SQW/OUT высокий уровень

enableSQW(enable);
Разрешение или запрет вывода прямоугольных импульсов заданной частоты на выводе SQW/OUT.
Параметры: 
enable: TRUE: Разрешить прямоугольные импульсы на выводе
                FALSE: Запретить прямоугольные импульсы на выводе
Возврат: Нет
Пример: rtc.enableSQW(true); // Использовать вывод SQW/OUT в качестве генератора прямоугольных импульсов

setSQWRate(rate);
Задание частоты прямоугольных импульсов на выводе SQW.
Параметры: 
     rate: SQW_RATE_1 - частота 1Гц
               SQW_RATE_4K - частота 4.096кГц
               SQW_RATE_8K - частота 8.192кГц
               SQW_RATE_32K - частота 32.768кГц
Возврат: Нет
Пример: rtc.setSQWRate(SQW_RATE_1); // Задать частоту на выводе SQW равной 1Гц


writeBuffer(buffer);
Записать данные из буфера в ОЗУ микросхемы.
Параметры: 
buffer: DS1307_RAM буфер
Возврат: Нет
Пример: rtc.writebuffer(ramBuffer); // Записать 56 байт из переменной ramBuffer в ОЗУ микросхемы

readBuffer();
Считать данные из ОЗУ микросхемы в буфер.
Параметры: Нет
Возврат: DS1307_RAM буфер
Пример: ramBuffer=rtc.readBuffer(); // Считать все 56 bytes из ОЗУ микросхемы в переменную ramBuffer

poke(address, value);
Записать 1 байт в ОЗУ микросхемы
Параметры: 
address: Адрес для записи байта (0-55)
value : Значение для записи по адресу <address> (0-255)
Возврат: Нет
Пример: rtc.poke(15, 160); // Записать 160 по адресу 15

peek(address);
Считать 1 байт из ОЗУ микросхемы
Параметры: 
address: Адрес для чтения байта (0-55)
Возврат: 1 байт данных, считанных из ОЗУ микросхемы
Пример: b=rtc.peek(18); // Считать 1 байт по адресу 18 и записать значение в переменную b