NAME
RPi::RTC::DS3231 - Interface to the DS3231 Real-Time Clock IC over I2C
SYNOPSIS
use RPi::RTC::DS3231;
my $rtc = RPi::RTC::DS3231->new;
# set individual
$rtc->month(12);
$rtc->hour(3);
$rt->sec(33);
# ...etc
# set date/time in one swoop
$rtc->date_time('2018-05-28 23:15:17');
# get individual
my $h = $rtc->hour;
my $d = $rtc->mday;
# ...etc
# get date/time as a string in one swoop
my $datetime = $rtc->date_time; # "yyyy-mm-dd hh:mm:ss"
# get/set 24 or 12 hour clock
my $ch = $rtc->clock_hours;
$rtc->clock_hours(24); # or 12
# get/set AM/PM
my $meridien = $rtc->am_pm;
$rtc->am_pm('AM'); # or 'PM' # only available in 24 hr clock mode
# get temperature
my $c = $rtc->temp;
my $f = $rtc->temp('f');
# get a hash ready for use in DateTime->new()
# must have DateTime installed!
my $dt = DateTime->new($rtc->dt_hash);DESCRIPTION
XS-based interface to the DS3231 Real-Time Clock Integrated Circuit over I2C. Although packaged under the RPi:: umbrella, the distribution will work on any Linux system with I2C installed and operable.
This distribution *should* work with the DS1307 modules as well, but I do not have one to test with.
METHODS
Operational Methods
new([$i2c_addr])
Instantiates and returns a new RPi::RTC::DS3231 object.
Parameters:
$i2c_addrOptional, Integer: The I2C address of the RTC module. Defaults to 0x68 for a DS3231 RTC unit.
Return: An RPi::RTC::DS3231 object.
close
Closes the active I2C (ioctl) file descriptor. Should be called at the end of your script.
Takes no parameters, has no return.
Individual time/date methods
year([$year])
Sets/gets the RTC year.
Parameters:
$yearOptional, Integer: A year between 2000 and 2099. If set, we'll update the RTC.
Return: Integer, the year currently stored in the RTC.
month([$month])
Sets/gets the RTC month.
Parameters:
$monthOptional, Integer: A month between 1 and 12. If set, we'll update the RTC.
Return: String/Integer, the month currently stored in the RTC, between 1 and 12. Single digits will be left-padded with a zero within a string.
mday([$mday])
Sets/gets the RTC day of the month.
Parameters:
$mdayOptional, Integer: A day between 1 and 31. If set, we'll update the RTC.
Return: String/Integer, the day currently stored in the RTC, between 1 and 31. Single digits will be left-padded with a zero within a string.
day([$day])
Sets/gets the RTC weekday.
Parameters:
$dayOptional, Integer: A weekday between 1 and 7 (correlates to Monday to Sunday respectively). If set, we'll update the RTC.
Return: String, the weekday currently stored in the RTC, as Monday to Sunday.
hour([$hour])
Sets/gets the RTC hour.
Parameters:
$hourOptional, Integer: An hour between 0 and 23. If set, we'll update the RTC.
Return: String/Integer, the hour currently stored in the RTC, between 0 and 23. Single digits will be left-padded with a zero within a string.
NOTE: If you're in 24-hour clock mode ("clock_hours"), valid values are 0 through 23. If in 12-hour clock mode, valid values are 1 through 12.
min([$min])
Sets/gets the RTC minute.
Parameters:
$minOptional, Integer: A minute between 0 and 59. If set, we'll update the RTC.
Return: String/Integer, the minute currently stored in the RTC, between 0 and 59. Single digits will be left-padded with a zero within a string.
sec([$sec])
Sets/gets the RTC second.
Parameters:
$secOptional, Integer: A second between 0 and 59. If set, we'll update the RTC.
Return: String/Integer, the second currently stored in the RTC, between 0 and 59. Single digits will be left-padded with a zero within a string.
Auxillary date/time methods
am_pm ([$meridien])
Sets/gets the time meridien (AM/PM) when in 12-hour clock mode. This method will croak() if called while in 24-hour clock format.
Parameters:
$meridienOptional, String: Set by sending in either AM for morning hours, or PM for latter hours.
Return: String: Returns either AM or PM.
clock_hours([$format])
Sets/gets the current clock format as either 12-hour or 24-hour format. By default, the RTC is set to 24-hour clock format.
Parameters:
$formatOptional, Integer: Send in 24 for 24-hour (aka. Military) clock format, or 12 for 12-hour clock format.
Return: Integer: The current format as either 24 or 12.
hms
Returns the current hours, minutes and seconds as a string in the following format:
'HH:MM:SS'If in 12-hour clock mode, we will append either AM or PM to the string as such:
'HH:MM:SS AM'date_time([$datetime])
Sets gets the date/time in one single operation.
Parameters:
$datetimeOptional, String: The date and time you want to set the RTC to, in the format:
'YYYY-MM-DD HH:MM:SS'Note that the hours must reflect 24-hour clock format, so for example, if you want to set 11 PM, use 23 for the hours field.
Return: String: The date and time in the format YYYY-MM-DD HH:MM:SS.
dt_hash
This is a convenience method that returns the date and time in hash format, ready to be used by DateTime's new() method.
Return: Hash: The format of the hash is as follows:
'minute' => 20,
'hour' => '02',
'year' => 2000,
'second' => '07',
'day' => 18,
'month' => '05'Example DateTime usage:
my $dt = DateTime->new($rtc->dt_hash);Miscellaneous methods
temp([$degrees])
The DS3231 has a built-in thermometer which you can leverage to get the current temperature. By default, we return the temperature in celcius. Send in 'f' to get the temperature in farenheit instead.
AUTHOR
Steve Bertrand, <steveb at cpan.org>
LICENSE AND COPYRIGHT
Copyright 2018 Steve Bertrand.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at: