Arduino:Библиотеки/Time

Содержание

Знакомство с Arduino

Продукты

Основы

Справочник языка Arduino

Примеры

Библиотеки

Хакинг

Изменения

Сравнение языков Arduino и Processing

Перевод: Максим Кузьмин

Проверка/Оформление/Редактирование: Мякишев Е.А.

Библиотека Time

Эта библиотека позволяет Arduino следить за временем, не используя для этого стороннее оборудование. Она позволяет скетчу получать информацию о текущем времени и дате: секунде, минуте, часе, дне, месяце и годе. Кроме того, она использует временной тип данных time_t (стандартный для языка C), что позволяет без труда рассчитать истекшее время и использовать полученные временные значения на разных платформах.

Примечание: Теперь доступны новые версии библиотек Time, TimeAlarms и DS1307RTC, которые были обновлены для новых версий Arduino и совместимости с Arduino Due. Код библиотеки Time обновлен и отличается от старой библиотеки DateTime, которая не работала с Arduino 1.6.1. В папке библиотеки Time также есть несколько скетчей-примеров, демонстрирующих ее использование, но для некоторых из них может потребоваться библиотека UDPbitewise, скачать которую можно здесь.

Дополнительную документацию ищите в файле «readme.txt», идущем в комплекте с библиотекой.

Загрузка

Чтобы загрузить библиотеку, пройдите по этой ссылке, кликните на зеленую кнопку Clone or download, а затем на Download ZIP. Когда ZIP-файл скачается, распакуйте его, а получившуюся папку переименуйте в «Time». Проверьте эту папку на наличие файлов «Time.cpp» и «Time.h».

Установка

Чтобы использовать библиотеку, поместите распакованный ZIP-файл в папку для библиотек IDE Arduino. Чтобы узнать, где находится эта папка на PC, откройте IDE Arduino, кликните на Файл > Настройки (File > Preferences) – адрес папки будет указан в самом верху, в поле «Размещение папки скетчей» (Sketchbook location). Затем перезапустите IDE Arduino. Если папки «libraries» нет, ее нужно создать.

Функции

Базовые функции

• Функция hour() считывает текущий час. Диапазон доступных значений: 0-23.
• Функция minute() считывает текущую минуту. Диапазон доступных значений: 0-59.
• Функция second() считывает текущую секунду. Диапазон доступных значений: 0-59.
• Функция day() считывает текущий день. Диапазон доступных значений: 0-31.
• Функция weekday() считывает текущий день недели. Воскресенье – это «1» и т.д.
• Функция month() считывает текущий месяц. Диапазон доступных значений: 1-12.
• Функция year() считывает текущий год. Возвращает четырехзначную цифру («2009», «2012» и т.д.)
• Функция setTime(t) выставляет системное время на время, сохраненное в переменной t. Эту функцию можно использовать в варианте setTime(hr,min,sec,day,month,yr), где шесть аргументов в скобочках – это значения, отвечающие за час, минуту, секунду, день, месяц и год.
• Функция adjustTime(adjustment) настраивает системное время при помощи добавления определенного значения.

Внимание: Функция adjustTime() несовместима с функцией setSyncProvider(), поскольку настраивает только системное время, но не время в синхронизаторе. То есть смещение времени при использовании adjustTime() будет потеряно при следующем использовании синхронизатора. Если время сместилось вперед, то вызов now(), скорее всего, причитает время от синхронизатора, чем системное время, настроенное библиотекой. Таким образом, если вы используете синхронизатор и вам нужно сосчитать настроенное время, то надеяться на now() не стоит, даже если вы вызываете эту функцию сразу после adjustTime().

Функции для работы с 12-часовым форматом

• Функция hourFormat() переключает библиотеку в слежение за временем в 12-часовом формате.
• Функция isAM() возвращает true, если текущее время – до полудня (AM).
• Функция isPM() возвращает true, если текущее время – после полудня (PM).

Для 32-битного типа данных «time_t»

Для времени используется специальный тип данных time_t, в котором хранится количество секунд, прошедших с 1 января 1970 года. Этот тип данных, состоящий из одного числа, упрощает хранение и сравнение данных о времени, потому что вам уже не приходится иметь дело с несколькими числами вроде количества дней в месяце, количества месяцев в году и т.д.

Работа с этими данными осуществляется через опциональный аргумент t, который указывается в функциях для считывания времени и даты. Это предотвращает ошибки в ситуациях, к примеру, когда между считыванием минуты и секунды начинается новая минута, и итоговые значения получаются некорректными. Использование опционального параметра устраняет эту проблему.

• Функция now() считывает время, прошедшее с 1 января 1970 года (в секундах).

Конструкция time_t t = now() сохраняет текущее время в переменную t.

• Функция hour(t) считывает час, сохраненный в переменной t.
• Функция minute(t) считывает минуту, сохраненную в переменной t.
• Функция second(t) считывает секунду, сохраненную в переменной t.
• Функция day(t) считывает день, сохраненный в переменной t.
• Функция weekday(t) считывает день недели, сохраненный в переменной t.
• Функция month() считывает месяц, сохраненный в переменной t.
• Функция year() считывает год, сохраненный в переменной t.

Другими словами, семь функций выше конвертируют переменную типа time_t в обычную единицу измерения времени (минуту, час, месяц и пр.). Возможно, этими функциями будет пользоваться проще, чем BreakTime() и 7-фрагментным аргументом tm (см. ниже).

• Функция makeTime(tm) конвертирует обычные дату и время в тип данных time_t. Соответственно, возвращаемое значение – тип данных time_t. Аргумент tm – переменная типа TimeElements, которая имеет следующие поля:

tm.Second    Секунды      0-59
tm.Minute    Минуты       0-59
tm.Hour      Часы         0-23
tm.Wday      Дни недели   0-6  (не нужно для mktime)
tm.Day       Дни          1-31
tm.Month     Месяцы       1-12
tm.Year      Годы         0-99 (отсчет начинается с 1970)

• Функция breakTime(t, tm) конвертирует тип данных time_t в обычные дату и время. Аргумент tm – переменная типа TimeElements, имеющая 7 полей и рассчитывающаяся на основе аргумента t.

Строковые функции

• monthStr()
• monthShortStr()
• dayStr()
• dayShortStr()

Обратите внимание, что для этих строковых функций нужен аргумент. Он не должен быть временной меткой (к примеру, time_t), а чем-то вроде month(). То есть в итоге у вас должно получиться что-то вроде monthStr(month()) или dayStr(weekday()).

Смотрите также пример «Передача строки даты по последовательному порту».

Функции для синхронизации с другими временными сервисами

• Функция timeStatus() сообщает, было ли задано время, а также было ли оно недавно синхронизировано. Возвращает одно из следующих значений: timeNotSet (время задано не было, отсчет начат с 1 января 1970 года), timeNeedsSync (время было задано, но попытка синхронизации не удалась) и timeSet (время было задано и синхронизировано).

Если функция вернула статус timeNotSet, то значения для времени и даты будут некорректными. Если функция вернет один из двух других статусов (timeNeedsSync и timeSet), то возвращаемые значения можно использовать, но при статусе timeNeedsSync время, возможно, будет немного сдвинуто.

• Функция setSyncProvider(getTimeFunction) настраивает время, автоматически вызывая функцию getTimeFunction(). Она считывает время у стороннего сервиса и возвращает значение типа time_t или «0» (если время неизвестно).
• Функция setSyncInterval(interval) задает количество секунд между синхронизациями. Другими словами, с ее помощью настраивается, как часто вызывается функция getTimeFunction(). Аргумент interval – это, собственно, интервальный период между синхронизациями.

Также в файле «TimeLib.h», который идет в комплекте с библиотекой, есть макросы для временных констант и преобразования единиц времени.

Примеры

• TimeArduinoDue - Синхронизация времени с помощью RTC (для Arduino Due)
• TimeGPS - Синхронизация времени с помощью GPS
• TimeNTP - Синхронизация времени с помощью NTP-сервера
• TimeNTP ESP8266WiFi - Синхронизация времени с помощью NTP-сервера и WiFi
• TimeRTC - Синхронизация времени с помощью RTC (для остальных Arduino)
• TimeRTCLog - Учет изменений состояний на контактах с помощью RTC
• TimeRTCSet - Установка RTC-времени
• TimeSerial - Настройка библиотеки Time при помощи последовательного порта
• TimeSerialDateStrings - Настройка библиотеки Time при помощи последовательного порта (со строковыми сообщениями)
• TimeTeensy3 - Синхронизация времени с помощью RTC на Teensy