From 9c71c64dcd2b2705774a0f3d00c9a5cbc8677afc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnim=20L=C3=A4uger?= Date: Fri, 31 Mar 2017 20:31:35 +0200 Subject: [PATCH] ds3231: require bit module, doc formatting (#1891) --- lua_modules/ds3231/ds3231-example.lua | 4 +- lua_modules/ds3231/ds3231-web.lua | 12 +- lua_modules/ds3231/ds3231.EN.md | 298 +++++++++++--------------- lua_modules/ds3231/ds3231.lua | 18 +- 4 files changed, 141 insertions(+), 191 deletions(-) diff --git a/lua_modules/ds3231/ds3231-example.lua b/lua_modules/ds3231/ds3231-example.lua index 5f3fb90c..340bb1be 100644 --- a/lua_modules/ds3231/ds3231-example.lua +++ b/lua_modules/ds3231/ds3231-example.lua @@ -1,9 +1,9 @@ -require("ds3231") -- ESP-01 GPIO Mapping gpio0, gpio2 = 3, 4 +i2c.setup(gpio0, gpio2, scl, i2c.SLOW) -- call i2c.setup() only once -ds3231.init(gpio0, gpio2) +require("ds3231") second, minute, hour, day, date, month, year = ds3231.getTime(); diff --git a/lua_modules/ds3231/ds3231-web.lua b/lua_modules/ds3231/ds3231-web.lua index 5a28e51f..db55854c 100644 --- a/lua_modules/ds3231/ds3231-web.lua +++ b/lua_modules/ds3231/ds3231-web.lua @@ -1,9 +1,11 @@ -require('ds3231') - -port = 80 -- ESP-01 GPIO Mapping gpio0, gpio2 = 3, 4 +i2c.setup(gpio0, gpio2, scl, i2c.SLOW) -- call i2c.setup() only once + +require('ds3231') + +port = 80 days = { [1] = "Sunday", @@ -30,8 +32,6 @@ months = { [12] = "December" } -ds3231.init(gpio0, gpio2) - srv=net.createServer(net.TCP) srv:listen(port, function(conn) @@ -51,4 +51,4 @@ srv:listen(port, "") conn:on("sent",function(conn) conn:close() end) end -) \ No newline at end of file +) diff --git a/lua_modules/ds3231/ds3231.EN.md b/lua_modules/ds3231/ds3231.EN.md index 0787ef70..57b4c6d0 100644 --- a/lua_modules/ds3231/ds3231.EN.md +++ b/lua_modules/ds3231/ds3231.EN.md @@ -1,67 +1,43 @@ -#DS3231 Module -##Require +# DS3231 Module + +## Require ```lua ds3231 = require("ds3231") ``` + ## Release ```lua ds3231 = nil package.loaded["ds3231"]=nil ``` - -##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 -**-** []() - - - ## 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) +#### Description +Sets the current date and time. +If _disableOscillator_ is set to 1 the oscillator will **stop** on battery. -####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 +#### Syntax +`ds3231.setTime(second, minute, hour, day, date, month, year[, disableOscillator])` -####Returns -nil +#### 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, defaults to 0 if omitted -####Example +#### Returns +`nil` + +#### Example ```lua +i2c.setup(3, 4, scl, i2c.SLOW) -- call i2c.setup() only once + 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); @@ -71,40 +47,37 @@ ds3231 = nil package.loaded["ds3231"]=nil ``` -####See also -**-** []() - - - ## getTime() -####Description + +#### Description Get the current date and time. -####Syntax -getTime() +#### Syntax +`ds3231.getTime()` -####Parameters -nil +#### Parameters +None -####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 +#### 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 +#### Example ```lua +i2c.setup(3, 4, scl, i2c.SLOW) -- call i2c.setup() only once + 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", +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 @@ -112,45 +85,45 @@ ds3231 = nil package.loaded["ds3231"]=nil ``` -####See also -**-** []() - ## setAlarm() -####Description + +#### 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). + +_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; +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) +#### Syntax +`ds3231.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) +#### 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 +#### Returns +`nil` -####Example +#### Example ```lua +i2c.setup(3, 4, scl, i2c.SLOW) -- call i2c.setup() only once + ds3231=require("ds3231") -ds3231.init(3, 4) -- Setting PIN1 to triggers on interrupt when alarm triggers gpio.mode(1,gpio.INT) @@ -167,28 +140,26 @@ ds3231 = nil package.loaded["ds3231"]=nil ``` -####See also -**-** []() - - ## reloadAlarms() -####Description + +#### 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() +#### Syntax +`ds3231.reloadAlarms()` -####Parameters -nil +#### Parameters +None -####Returns -nil +#### Returns +`nil` -####Example +#### Example ```lua +i2c.setup(3, 4, scl, i2c.SLOW) -- call i2c.setup() only once + ds3231=require("ds3231") -ds3231.init(3, 4) -- Setting PIN1 to triggers on interrupt when alarm triggers gpio.mode(1,gpio.INT) @@ -205,27 +176,25 @@ ds3231 = nil package.loaded["ds3231"]=nil ``` -####See also -**-** []() - - ## enableAlarm() -####Description + +#### Description Enable an already setted alarm with the previous matching conditions. It reloads alarms internally. -####Syntax -enableAlarm(alarmId) +#### Syntax +`ds3231.enableAlarm(alarmId)` -####Parameters -alarmId: 1-2 +#### Parameters +`alarmId`: 1-2 -####Returns -nil +#### Returns +`nil` -####Example +#### Example ```lua +i2c.setup(3, 4, scl, i2c.SLOW) -- call i2c.setup() only once + ds3231=require("ds3231") -ds3231.init(3, 4) -- Trigger on x:20:15 ds3231.setAlarm(1,ds3231.MINUTE,15,20) @@ -243,29 +212,29 @@ ds3231 = nil package.loaded["ds3231"]=nil ``` -####See also -**-** []() - - ## disableAlarm() -####Description -Disable an already setted alarm with the previous matching conditions. -if _alarmId_ is not 1 or 2 it disables both alarms. + +#### 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) +#### Syntax +`ds3231.disableAlarm(alarmId)` -####Parameters -alarmId: 0-2 +#### Parameters +`alarmId: 0-2` -####Returns -nil +#### Returns +`nil` -####Example +#### Example ```lua +i2c.setup(3, 4, scl, i2c.SLOW) -- call i2c.setup() only once + ds3231=require("ds3231") -ds3231.init(3, 4) -- Trigger on x:20:15 ds3231.setAlarm(1,ds3231.MINUTE,15,20) @@ -283,28 +252,26 @@ ds3231 = nil package.loaded["ds3231"]=nil ``` -####See also -**-** []() - - ## getBytes() -####Description + +#### 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() +#### Syntax +`ds3231.getBytes()` -####Parameters -nil +#### Parameters +None -####Returns -control: integer. Control 0-255 -status: integer. Status 0-143 (bit 6-5-4 unused) +#### Returns +- `control`: integer. Control 0-255 +- `status`: integer. Status 0-143 (bit 6-5-4 unused) -####Example +#### Example ```lua +i2c.setup(3, 4, scl, i2c.SLOW) -- call i2c.setup() only once + ds3231=require("ds3231") -ds3231.init(3, 4) control,status = ds3231.getBytes() print('Control byte: '..control) @@ -315,29 +282,27 @@ ds3231 = nil package.loaded["ds3231"]=nil ``` -####See also -**-** []() - - ## 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. + +#### 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 set 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() +#### Syntax +`ds3231.resetStopFlag()` -####Parameters -nil +#### Parameters +None -####Returns -nil +#### Returns +`nil` -####Example +#### Example ```lua +i2c.setup(3, 4, scl, i2c.SLOW) -- call i2c.setup() only once + ds3231=require("ds3231") -ds3231.init(3, 4) control,status = ds3231.getBytes() if bit.band(bit.rshift(status, 7),1) == 1 then @@ -349,6 +314,3 @@ end ds3231 = nil package.loaded["ds3231"]=nil ``` - -####See also -**-** []() \ No newline at end of file diff --git a/lua_modules/ds3231/ds3231.lua b/lua_modules/ds3231/ds3231.lua index a93064ca..e7f848b7 100644 --- a/lua_modules/ds3231/ds3231.lua +++ b/lua_modules/ds3231/ds3231.lua @@ -5,6 +5,9 @@ -- Tobie Booth -------------------------------------------------------------------------------- +require("bit") +require("i2c") + local moduleName = ... local M = {} _G[moduleName] = M @@ -39,21 +42,6 @@ local function addAlarmBit(val,day) return bit.bor(val,128) end --- initialize i2c ---parameters: ---d: sda ---l: scl -function M.init(d, l) - if (d ~= nil) and (l ~= nil) and (d >= 0) and (d <= 11) and (l >= 0) and ( l <= 11) and (d ~= l) then - sda = d - scl = l - else - print("[ERROR] i2c config failed!") return nil - end - print("[LOG] DS3231 init done") - i2c.setup(id, sda, scl, i2c.SLOW) -end - --get time from DS3231 function M.getTime() i2c.start(id)