/ 
RPi-RTC-DS3231-0.01
River stage one • 1 direct dependent • 2 total dependents
/ RPi::RTC::DS3231

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_addr

Optional, 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:

$year

Optional, 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:

$month

Optional, 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:

$mday

Optional, 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:

$day

Optional, 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:

$hour

Optional, 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:

$min

Optional, 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:

$sec

Optional, 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:

$meridien

Optional, 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:

$format

Optional, 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:

$datetime

Optional, 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:

http://www.perlfoundation.org/artistic_license_2_0