[feat, Kobo] Autoshutdown (#5335)

The methods used here will likely work on most embedded devices, which is why I put them in their own WakeupMgr interface/scheduler module, separate from Kobo.

See https://www.mobileread.com/forums/showthread.php?p=3886403#post3886403 for more context.

Fixes #3806.

frontend/device/kobo/device.lua

@@ -1,9 +1,10 @@
 local Generic = require("device/generic/device")
-local TimeVal = require("ui/timeval")
 local Geom = require("ui/geometry")
+local TimeVal = require("ui/timeval")
+local WakeupMgr = require("device/wakeupmgr")
+local logger = require("logger")
 local util = require("ffi/util")
 local _ = require("gettext")
-local logger = require("logger")
 
 local function yes() return true end
 local function no() return false end
@@ -313,6 +314,7 @@ function Kobo:init()
             end,
         }
     }
+    self.wakeup_mgr = WakeupMgr:new()
 
     Generic.init(self)
 
@@ -535,20 +537,34 @@ end
 
 local unexpected_wakeup_count = 0
 local function check_unexpected_wakeup()
-    logger.dbg("Kobo suspend: checking unexpected wakeup:",
-               unexpected_wakeup_count)
-    if unexpected_wakeup_count == 0 or unexpected_wakeup_count > 20 then
-        -- Don't put device back to sleep under the following two cases:
-        --   1. a resume event triggered Kobo:resume() function
-        --   2. trying to put device back to sleep more than 20 times after unexpected wakeup
-        return
-    end
-
-    logger.err("Kobo suspend: putting device back to sleep, unexpected wakeups:",
-               unexpected_wakeup_count)
+    local UIManager = require("ui/uimanager")
     -- just in case other events like SleepCoverClosed also scheduled a suspend
-    require("ui/uimanager"):unschedule(Kobo.suspend)
-    Kobo.suspend()
+    UIManager:unschedule(Kobo.suspend)
+
+    if WakeupMgr:isWakeupAlarmScheduled() and WakeupMgr:validateWakeupAlarmByProximity() then
+        logger.dbg("Kobo suspend: scheduled wakeup.")
+        local res = WakeupMgr:wakeupAction()
+        if not res then
+            logger.err("Kobo suspend: wakeup action failed.")
+        end
+        logger.dbg("Kobo suspend: putting device back to sleep.")
+        -- Most wakeup actions are linear, but we need some leeway for the
+        -- poweroff action to send out close events to all requisite widgets.
+        UIManager:scheduleIn(30, Kobo.suspend)
+    else
+        logger.dbg("Kobo suspend: checking unexpected wakeup:",
+                   unexpected_wakeup_count)
+        if unexpected_wakeup_count == 0 or unexpected_wakeup_count > 20 then
+            -- Don't put device back to sleep under the following two cases:
+            --   1. a resume event triggered Kobo:resume() function
+            --   2. trying to put device back to sleep more than 20 times after unexpected wakeup
+            return
+        end
+
+        logger.err("Kobo suspend: putting device back to sleep. Unexpected wakeups:",
+                   unexpected_wakeup_count)
+        Kobo.suspend()
+    end
 end
 
 function Kobo:getUnexpectedWakeup() return unexpected_wakeup_count end
@@ -683,7 +699,7 @@ function Kobo:suspend()
     -- expected wakeup, which gets checked in check_unexpected_wakeup().
     unexpected_wakeup_count = unexpected_wakeup_count + 1
     -- assuming Kobo:resume() will be called in 15 seconds
-    logger.dbg("Kobo suspend: scheduing unexpected wakeup guard")
+    logger.dbg("Kobo suspend: scheduling unexpected wakeup guard")
     UIManager:scheduleIn(15, check_unexpected_wakeup)
 end
 

frontend/device/wakeupmgr.lua

@@ -0,0 +1,187 @@
+--[[--
+RTC wakeup interface.
+
+Many devices can schedule hardware wakeups with a real time clock alarm.
+On embedded devices this can typically be easily manipulated by the user
+through `/sys/class/rtc/rtc0/wakealarm`. Some, like the Kobo Aura H2O,
+can only schedule wakeups through ioctl.
+
+See @{ffi.rtc} for implementation details.
+
+See also: <https://linux.die.net/man/4/rtc>.
+--]]
+
+local RTC = require("ffi/rtc")
+local logger = require("logger")
+
+--[[--
+WakeupMgr base class.
+
+@table WakeupMgr
+--]]
+local WakeupMgr = {
+    dev_rtc = "/dev/rtc0", -- RTC device
+    _task_queue = {},      -- Table with epoch at which to schedule the task and the function to be scheduled.
+}
+
+--[[--
+Initiate a WakeupMgr instance.
+
+@usage
+local WakeupMgr = require("device/wakeupmgr")
+local wakeup_mgr = WakeupMgr:new{
+    -- The default is `/dev/rtc0`, but some devices have more than one RTC.
+    -- You might therefore need to use `/dev/rtc1`, etc.
+    dev_rtc = "/dev/rtc0",
+}
+--]]
+function WakeupMgr:new(o)
+    o = o or {}
+    setmetatable(o, self)
+    self.__index = self
+    if o.init then o:init() end
+    return o
+end
+
+--[[--
+Add a task to the queue.
+
+@todo Group by type to avoid useless wakeups.
+For example, maintenance, sync, and shutdown.
+I'm not sure if the distinction between maintenance and sync makes sense
+but it's wifi on vs. off.
+--]]
+function WakeupMgr:addTask(seconds_from_now, callback)
+    if not type(seconds_from_now) == "number" and not type(callback) == "function" then return end
+
+    local epoch = RTC:secondsFromNowToEpoch(seconds_from_now)
+
+    local old_upcoming_task = (self._task_queue[1] or {}).epoch
+
+    table.insert(self._task_queue, {
+        epoch = epoch,
+        callback = callback,
+    })
+    --- @todo Binary insert? This table should be so small that performance doesn't matter.
+    -- It might be useful to have that available as a utility function regardless.
+    table.sort(self._task_queue, function(a, b) return a.epoch < b.epoch end)
+
+    local new_upcoming_task = self._task_queue[1].epoch
+
+    if not old_upcoming_task or (new_upcoming_task < old_upcoming_task) then
+        self:setWakeupAlarm(self._task_queue[1].epoch)
+    end
+end
+
+--[[--
+Remove task from queue.
+
+This method removes a task by either index, scheduled time or callback.
+
+@int idx Task queue index. Mainly useful within this module.
+@int epoch The epoch for when this task is scheduled to wake up.
+Normally the preferred method for outside callers.
+@int callback A scheduled callback function. Store a reference for use
+with anonymous functions.
+--]]
+function WakeupMgr:removeTask(idx, epoch, callback)
+    if not type(idx) == "number"
+        and not type(epoch) == "number"
+        and not type(callback) == "function" then return end
+
+    if #self._task_queue < 1 then return end
+
+    for k, v in ipairs(self._task_queue) do
+        if k == idx or epoch == v.epoch or callback == v.callback then
+            table.remove(self._task_queue, k)
+            return true
+        end
+    end
+end
+
+--[[--
+Execute wakeup action.
+
+This method should be called by the device resume logic in case of a scheduled wakeup.
+
+It checks if the wakeup was scheduled by us using @{validateWakeupAlarmByProximity},
+executes the task, and schedules the next wakeup if any.
+
+@treturn bool
+--]]
+function WakeupMgr:wakeupAction()
+    if #self._task_queue > 0 then
+        local task = self._task_queue[1]
+        if self:validateWakeupAlarmByProximity(task.epoch) then
+            task.callback()
+            self:removeTask(1)
+            if self._task_queue[1] then
+                -- Set next scheduled wakeup, if any.
+                self:setWakeupAlarm(self._task_queue[1].epoch)
+            end
+            return true
+        else
+            return false
+        end
+    end
+end
+
+--[[--
+Set wakeup alarm.
+
+Simple wrapper for @{ffi.rtc.setWakeupAlarm}.
+--]]
+function WakeupMgr:setWakeupAlarm(epoch, enabled)
+    return RTC:setWakeupAlarm(epoch, enabled)
+end
+
+--[[--
+Unset wakeup alarm.
+
+Simple wrapper for @{ffi.rtc.unsetWakeupAlarm}.
+--]]
+function WakeupMgr:unsetWakeupAlarm()
+    return RTC:unsetWakeupAlarm()
+end
+
+--[[--
+Get wakealarm as set by us.
+
+Simple wrapper for @{ffi.rtc.getWakeupAlarm}.
+--]]
+function WakeupMgr:getWakeupAlarm()
+    return RTC:getWakeupAlarm()
+end
+
+--[[--
+Get RTC wakealarm from system.
+
+Simple wrapper for @{ffi.rtc.getWakeupAlarm}.
+--]]
+function WakeupMgr:getWakeupAlarmSys()
+    return RTC:getWakeupAlarmSys()
+end
+
+--[[--
+Validate wakeup alarm.
+
+Checks if we set the alarm.
+
+Simple wrapper for @{ffi.rtc.validateWakeupAlarmByProximity}.
+--]]
+function WakeupMgr:validateWakeupAlarmByProximity()
+    return RTC:validateWakeupAlarmByProximity()
+end
+
+--[[--
+Check if a wakeup is scheduled.
+
+Simple wrapper for @{ffi.rtc.isWakeupAlarmScheduled}.
+--]]
+function WakeupMgr:isWakeupAlarmScheduled()
+    local wakeup_scheduled = RTC:isWakeupAlarmScheduled()
+    logger.dbg("isWakeupAlarmScheduled", wakeup_scheduled)
+    return wakeup_scheduled
+end
+
+return WakeupMgr

frontend/ui/elements/filemanager_menu_order.lua

@@ -42,6 +42,7 @@ local order = {
         "time",
         "battery",
         "autosuspend",
+        "autoshutdown",
         "ignore_sleepcover",
         "ignore_open_sleepcover",
         "mass_storage_settings",

frontend/ui/elements/reader_menu_order.lua

@@ -61,6 +61,7 @@ local order = {
         "time",
         "battery",
         "autosuspend",
+        "autoshutdown",
         "ignore_sleepcover",
         "ignore_open_sleepcover",
         "mass_storage_settings",

frontend/ui/uimanager.lua

@@ -386,7 +386,7 @@ function UIManager:close(widget, refreshtype, refreshregion, refreshdither)
 end
 
 -- schedule an execution task, task queue is in ascendant order
-function UIManager:schedule(time, action)
+function UIManager:schedule(time, action, ...)
     local p, s, e = 1, 1, #self._task_queue
     if e ~= 0 then
         local us = time[1] * MILLION + time[2]
@@ -416,7 +416,11 @@ function UIManager:schedule(time, action)
             end
         until e < s
     end
-    table.insert(self._task_queue, p, { time = time, action = action })
+    table.insert(self._task_queue, p, {
+        time = time,
+        action = action,
+        args = {...},
+    })
     self._task_queue_dirty = true
 end
 dbg:guard(UIManager, 'schedule',
@@ -426,7 +430,7 @@ dbg:guard(UIManager, 'schedule',
     end)
 
 --- Schedules task in a certain amount of seconds (fractions allowed) from now.
-function UIManager:scheduleIn(seconds, action)
+function UIManager:scheduleIn(seconds, action, ...)
     local when = { util.gettime() }
     local s = math.floor(seconds)
     local usecs = (seconds - s) * MILLION
@@ -436,7 +440,7 @@ function UIManager:scheduleIn(seconds, action)
         when[1] = when[1] + 1
         when[2] = when[2] - MILLION
     end
-    self:schedule(when, action)
+    self:schedule(when, action, ...)
 end
 dbg:guard(UIManager, 'scheduleIn',
     function(self, seconds, action)
@@ -743,7 +747,7 @@ function UIManager:_checkTasks()
             -- task is pending to be executed right now. do it.
             -- NOTE: be careful that task.action() might modify
             -- _task_queue here. So need to avoid race condition
-            task.action()
+            task.action(unpack(task.args or {}))
         else
             -- queue is sorted in ascendant order, safe to assume all items
             -- are future tasks for now