354 lines
7.3 KiB
Markdown
354 lines
7.3 KiB
Markdown
#DS3231 Module
|
|
##Require
|
|
```lua
|
|
ds3231 = require("ds3231")
|
|
```
|
|
## Release
|
|
```lua
|
|
ds3231 = nil
|
|
package.loaded["ds3231"]=nil
|
|
```
|
|
<a id="ds3231_init"></a>
|
|
##init()
|
|
####Description
|
|
Setting the pins of DS3231.
|
|
|
|
####Syntax
|
|
init(sda, scl)
|
|
|
|
####Parameters
|
|
sda: 1~10, IO index.
|
|
scl: 1~10, IO index.
|
|
|
|
####Returns
|
|
nil
|
|
|
|
####Example
|
|
```lua
|
|
ds3231 = require("ds3231")
|
|
ds3231.init(3, 4)
|
|
-- Don't forget to release it after use
|
|
ds3231 = nil
|
|
package.loaded["ds3231"]=nil
|
|
```
|
|
|
|
####See also
|
|
**-** []()
|
|
|
|
|
|
<a id="ds3231_settime"></a>
|
|
## setTime()
|
|
####Description
|
|
Sets the current date and time.
|
|
if _disableOscillator_ is set to 1 the oscillator will **stop** on battery.
|
|
|
|
####Syntax
|
|
setTime(second, minute, hour, day, date, month, year, disableOscillator)
|
|
|
|
####Parameters
|
|
second: 00-59
|
|
minute: 00-59
|
|
hour: 00-23
|
|
day: 1-7 (Sunday = 1, Saturday = 7)
|
|
date: 01-31
|
|
month: 01-12
|
|
year: 00-99
|
|
disableOscillator: (optional) 0-1
|
|
|
|
####Returns
|
|
nil
|
|
|
|
####Example
|
|
```lua
|
|
ds3231 = require("ds3231")
|
|
ds3231.init(3, 4)
|
|
|
|
-- Set date and time to Sunday, January 18th 2015 6:30PM
|
|
ds3231.setTime(0, 30, 18, 1, 18, 1, 15);
|
|
|
|
-- Don't forget to release it after use
|
|
ds3231 = nil
|
|
package.loaded["ds3231"]=nil
|
|
```
|
|
|
|
####See also
|
|
**-** []()
|
|
|
|
|
|
<a id="ds3231_getTime"></a>
|
|
## getTime()
|
|
####Description
|
|
Get the current date and time.
|
|
|
|
####Syntax
|
|
getTime()
|
|
|
|
####Parameters
|
|
nil
|
|
|
|
####Returns
|
|
second: integer. Second 00-59
|
|
minute: integer. Minute 00-59
|
|
hour: integer. Hour 00-23
|
|
day: integer. Day 1-7 (Sunday = 1, Saturday = 7)
|
|
date: integer. Date 01-31
|
|
month: integer. Month 01-12
|
|
year: integer. Year 00-99
|
|
|
|
####Example
|
|
```lua
|
|
ds3231=require("ds3231")
|
|
ds3231.init(3, 4)
|
|
|
|
-- Get date and time
|
|
second, minute, hour, day, date, month, year = ds3231.getTime();
|
|
|
|
-- Print date and time
|
|
print(string.format("Time & Date: %s:%s:%s %s/%s/%s",
|
|
hour, minute, second, date, month, year))
|
|
|
|
-- Don't forget to release it after use
|
|
ds3231 = nil
|
|
package.loaded["ds3231"]=nil
|
|
|
|
```
|
|
####See also
|
|
**-** []()
|
|
|
|
<a id="ds3231_setAlarm"></a>
|
|
## setAlarm()
|
|
####Description
|
|
Set an alarm to be triggered on SQW pin:
|
|
_alarm1_ has a precision of **seconds**; _alarm2_ has a precision of **minutes** (`second` parameter will be ignored).
|
|
|
|
Alarms sets gpio.LOW over the SQW pin and let it unchanged until reloaded. When reloaded sets gpio.HIGH.
|
|
Alarms trigger **only once**, after that, if you want them to trigger again, you need to call `reloadAlarms()` or `setAlarm(...)` again.
|
|
|
|
Alarm type set the alarm match conditions:
|
|
- `ds3231.EVERYSECOND` works only with _alarm1_ and triggers every second;
|
|
- `ds3231.EVERYMINUTE` works only with _alarm2_ and triggers every minute (at 00 seconds);
|
|
- `ds3231.SECOND` triggers when time match given `seconds` parameter;
|
|
- `ds3231.MINUTE` triggers when time match given `seconds` and `minutes` parameters;
|
|
- `ds3231.HOUR` triggers when time match given `seconds`, `minutes`, and `hours` parameters;
|
|
- `ds3231.DAY` triggers when time match given `seconds`, `minutes`, and `hours` on week day `date/day` parameters;
|
|
- `ds3231.DATE` triggers when time match given `seconds`, `minutes`, and `hours` on date (day of the month) `date/day` parameters;
|
|
|
|
####Syntax
|
|
setAlarm(alarmId, alarmType, seconds, minutes, hours, date/day)
|
|
|
|
####Parameters
|
|
alarmId: 1-2
|
|
alarmType: 1-7
|
|
seconds: 00-59
|
|
minutes: 00-59
|
|
hours: 00-23
|
|
date/day: 01-31 or 1-7 (Sunday = 1, Saturday = 7)
|
|
|
|
####Returns
|
|
nil
|
|
|
|
####Example
|
|
```lua
|
|
ds3231=require("ds3231")
|
|
ds3231.init(3, 4)
|
|
|
|
-- Setting PIN1 to triggers on interrupt when alarm triggers
|
|
gpio.mode(1,gpio.INT)
|
|
gpio.trig(1,'down',function(level)
|
|
print('Time is passing')
|
|
-- If not reloaded it will be triggered only once
|
|
ds3231.reloadAlarms()
|
|
end)
|
|
|
|
ds3231.setAlarm(2,ds3231.EVERYMINUTE)
|
|
|
|
-- Don't forget to release it after use
|
|
ds3231 = nil
|
|
package.loaded["ds3231"]=nil
|
|
```
|
|
|
|
####See also
|
|
**-** []()
|
|
|
|
<a id="ds3231_reloadAlarms"></a>
|
|
## reloadAlarms()
|
|
####Description
|
|
Reload an already triggered alarm. Otherwise it will never be triggered again.
|
|
There are two different alarms and they have to be reloaded both to let, even only one, to be triggered again. So there isn't a param to select which alarm to reload.
|
|
|
|
####Syntax
|
|
reloadAlarms()
|
|
|
|
####Parameters
|
|
nil
|
|
|
|
####Returns
|
|
nil
|
|
|
|
####Example
|
|
```lua
|
|
ds3231=require("ds3231")
|
|
ds3231.init(3, 4)
|
|
|
|
-- Setting PIN1 to triggers on interrupt when alarm triggers
|
|
gpio.mode(1,gpio.INT)
|
|
gpio.trig(1,'down',function(level)
|
|
print('Time is passing')
|
|
-- If not reloaded it will be triggered only once
|
|
ds3231.reloadAlarms()
|
|
end)
|
|
|
|
ds3231.setAlarm(2,ds3231.EVERYMINUTE)
|
|
|
|
-- Don't forget to release it after use
|
|
ds3231 = nil
|
|
package.loaded["ds3231"]=nil
|
|
```
|
|
|
|
####See also
|
|
**-** []()
|
|
|
|
<a id="ds3231_enableAlarm"></a>
|
|
## enableAlarm()
|
|
####Description
|
|
Enable an already setted alarm with the previous matching conditions. It reloads alarms internally.
|
|
|
|
####Syntax
|
|
enableAlarm(alarmId)
|
|
|
|
####Parameters
|
|
alarmId: 1-2
|
|
|
|
####Returns
|
|
nil
|
|
|
|
####Example
|
|
```lua
|
|
ds3231=require("ds3231")
|
|
ds3231.init(3, 4)
|
|
|
|
-- Trigger on x:20:15
|
|
ds3231.setAlarm(1,ds3231.MINUTE,15,20)
|
|
|
|
if badThing == 1 then
|
|
ds3231.disableAlarm(1)
|
|
end
|
|
|
|
if goodThing == 1 then
|
|
ds3231.enableAlarm(1)
|
|
end
|
|
|
|
-- Don't forget to release it after use
|
|
ds3231 = nil
|
|
package.loaded["ds3231"]=nil
|
|
```
|
|
|
|
####See also
|
|
**-** []()
|
|
|
|
<a id="ds3231_disableAlarm"></a>
|
|
## disableAlarm()
|
|
####Description
|
|
Disable an already setted alarm with the previous matching conditions.
|
|
if _alarmId_ is not 1 or 2 it disables both alarms.
|
|
**Warning**: `disableAlarm()` prevent alarms to trigger interrupt over SQW pin but alarm itself will triggers at the matching conditions as it could be seen on _status byte_.
|
|
|
|
####Syntax
|
|
disableAlarm(alarmId)
|
|
|
|
####Parameters
|
|
alarmId: 0-2
|
|
|
|
####Returns
|
|
nil
|
|
|
|
####Example
|
|
```lua
|
|
ds3231=require("ds3231")
|
|
ds3231.init(3, 4)
|
|
|
|
-- Trigger on x:20:15
|
|
ds3231.setAlarm(1,ds3231.MINUTE,15,20)
|
|
|
|
if badThing == 1 then
|
|
ds3231.disableAlarm(1)
|
|
end
|
|
|
|
if goodThing == 1 then
|
|
ds3231.enableAlarm(1)
|
|
end
|
|
|
|
-- Don't forget to release it after use
|
|
ds3231 = nil
|
|
package.loaded["ds3231"]=nil
|
|
```
|
|
|
|
####See also
|
|
**-** []()
|
|
|
|
<a id="ds3231_getBytes"></a>
|
|
## getBytes()
|
|
####Description
|
|
Get bytes of control, for debug purpose, and status of DS3231. To see what they means check the [Datasheet](http://datasheets.maximintegrated.com/en/ds/DS3231.pdf)
|
|
|
|
####Syntax
|
|
getBytes()
|
|
|
|
####Parameters
|
|
nil
|
|
|
|
####Returns
|
|
control: integer. Control 0-255
|
|
status: integer. Status 0-143 (bit 6-5-4 unused)
|
|
|
|
####Example
|
|
```lua
|
|
ds3231=require("ds3231")
|
|
ds3231.init(3, 4)
|
|
|
|
control,status = ds3231.getBytes()
|
|
print('Control byte: '..control)
|
|
print('Status byte: '..status)
|
|
|
|
-- Don't forget to release it after use
|
|
ds3231 = nil
|
|
package.loaded["ds3231"]=nil
|
|
```
|
|
|
|
####See also
|
|
**-** []()
|
|
|
|
<a id="ds3231_resetStopFlag"></a>
|
|
## resetStopFlag()
|
|
####Description
|
|
Stop flag on status byte means that the oscillator either is stopped or was stopped for some period and may be used to judge the validity of the timekeeping data.
|
|
When setted to 1 this flag keeps that values until changed to 0.
|
|
Call `resetStopFlag()` if you need to check validity of time data after that.
|
|
|
|
####Syntax
|
|
resetStopFlag()
|
|
|
|
####Parameters
|
|
nil
|
|
|
|
####Returns
|
|
nil
|
|
|
|
####Example
|
|
```lua
|
|
ds3231=require("ds3231")
|
|
ds3231.init(3, 4)
|
|
|
|
control,status = ds3231.getBytes()
|
|
if bit.band(bit.rshift(status, 7),1) == 1 then
|
|
print('[WARNING] RTC has stopped')
|
|
ds3231.resetStopFlag()
|
|
end
|
|
|
|
-- Don't forget to release it after use
|
|
ds3231 = nil
|
|
package.loaded["ds3231"]=nil
|
|
```
|
|
|
|
####See also
|
|
**-** []() |