Inspired by http://developer.android.com/reference/android/os/PowerManager.html The idea is to create a DOM API to control the power consumed by the device, from adjusting the screen brightness to turning the power off. And we need a way to track the user activity and try to put the device into low power state when the user is idle. Current interface: interface nsIDOMMozPowerManager : nsISupports { attribute double screenBrightness; attribute boolean screenEnabled; attribute unsigned long timeout; void sleep(); void powerOff(in boolean reboot); void userActivity(in boolean aNoChangeLights); [implicit_jscontext] nsIDOMMozWakeLock requestWakeLock(in jsval policy, in ACString id); // // policy = { cpu: "on", // screen: "dim", "bright", "off", "on", // keyboard: "on", "off", // wakeup: "on" } }; interface nsIDOMMozWakeLock : nsISupports { readonly attribute boolean isHeld; void unlock(); };
Some questions about this API: What is |timeout|? screenTimeout? What does userActivity() do? Is that what I'm supposed to call when the user does something? If so, maybe we could improve that name. Also, what does the boolean do? (I have a personal vendetta against functions which take opaque boolean args, so maybe we can split this into two functions.) Do we need both screenEnabled and sleep()? If I call sleep() while holding the appropriate wake lock, we'll only turn off the display, right? Is there a way to programmatically wake up after calling sleep()? I'd prefer powerOff() and reboot() as separate functions. With respect to the wake lock policy: * Do "cpu" and "wakeup" always need to be "on"? Is there another option? * What's the difference between "screen: dim" and "screen: on"? In both cases, I'm requesting that the screen not automatically turn off, right? The big question here is: How much of our power management are we going to do in JS? I suspect, for example, that we'll manage the screen's brightness from JS. In that case, then we need an API for reading whether there are any wake locks held on the screen, and we probably don't need the |timeout| property. In fact, the API that content can touch (requestWakeLock) should almost certainly be separate from the API that privileged code touches.
Kan-Ru, you'll probably have an easier time getting these changes in if you break this API up into smaller pieces and address them in separate bugs: * reboot / shutdown * moving screenEnabled / screenBrightness * wake locks / idle notification I'd probably do wake lock / idle notification last, because that's going to be tricky.
See also discussion in https://github.com/andreasgal/gaia/issues/167
(In reply to Justin Lebar [:jlebar] from comment #1) > Some questions about this API: > > What is |timeout|? screenTimeout? Yes. The timeout before screen locks. > What does userActivity() do? Is that what I'm supposed to call when the > user does something? If so, maybe we could improve that name. Also, what > does the boolean do? (I have a personal vendetta against functions which > take opaque boolean args, so maybe we can split this into two functions.) It should notify the idle tracker when the user does something. The boolean says if the event should brighten the screen or not. This probably could be controlled by hard/soft policy, or managed by the apps. > Do we need both screenEnabled and sleep()? If I call sleep() while holding > the appropriate wake lock, we'll only turn off the display, right? Is there > a way to programmatically wake up after calling sleep()? We still need a way to know the exact screen state. Android uses alarm event to wake up the device programmatically. > I'd prefer powerOff() and reboot() as separate functions. Agree. > With respect to the wake lock policy: > * Do "cpu" and "wakeup" always need to be "on"? Is there another option? > * What's the difference between "screen: dim" and "screen: on"? In both > cases, I'm requesting that the screen not automatically turn off, right? Someone(chris?) says "cpu: off" might be useful for eink device. The screen policy is requesting the minimum screen brightness. > The big question here is: How much of our power management are we going to > do in JS? I suspect, for example, that we'll manage the screen's brightness > from JS. In that case, then we need an API for reading whether there are > any wake locks held on the screen, and we probably don't need the |timeout| > property. I think most of the power management code can be done is JS. Only idle tracking, power on/off and wakelock that need HAL need native code. > > In fact, the API that content can touch (requestWakeLock) should almost > certainly be separate from the API that privileged code touches.
We should split out the powerOff / reboot API and moving screen.enabled/brightness into two new bugs, since the wake lock API is pretty complicated. You can file a separate bug on the wake lock API and mark all three as blocking this one, or you can file two new bugs and switch the lock API discussion to bug 697132, or you can dupe bug 697132 here...we just need one bug per issue, please. > Yes. The timeout before screen locks. Okay, so we're getting rid of this in favor of handling this in Gaia, right? (re |userActivity|) > The boolean says if the event should brighten the screen or not. This probably could be controlled > by hard/soft policy, or managed by the apps. I don't think we need an API for notifying Gecko that a touch or button click happened. Gecko generates these events itself. It's conceivable that we'd want an API for the page to say "hey, something happened on the screen; treat it as though the user tapped or clicked." For example, you're in a chat program and your buddy responds; you don't want the screen to immediately go dark. But I think this API is a low priority compared to the rest here, and we should drop it for now. > Someone(chris?) says "cpu: off" might be useful for eink device. What does wakeup: off do? And what's the difference between "screen: on" and "screen: dim"? Also, I don't understand what the keyboard lock is supposed to do. > I think most of the power management code can be done is JS. Agreed. Can you please post a new proposed API? (It's actually two APIs; one for privileged code managing the power state, and the other for content.)
(In reply to Justin Lebar [:jlebar] from comment #5) > We should split out the powerOff / reboot API and moving > screen.enabled/brightness into two new bugs, since the wake lock API is > pretty complicated. You can file a separate bug on the wake lock API and > mark all three as blocking this one, or you can file two new bugs and switch > the lock API discussion to bug 697132, or you can dupe bug 697132 here...we > just need one bug per issue, please. Sure. Let's move the lock API discussion to bug 697132. > > Yes. The timeout before screen locks. > > Okay, so we're getting rid of this in favor of handling this in Gaia, right? Yes. > (re |userActivity|) > I don't think we need an API for notifying Gecko that a touch or button > click happened. Gecko generates these events itself. > > It's conceivable that we'd want an API for the page to say "hey, something > happened on the screen; treat it as though the user tapped or clicked." For > example, you're in a chat program and your buddy responds; you don't want > the screen to immediately go dark. But I think this API is a low priority > compared to the rest here, and we should drop it for now. Agreed. And it can be done in Gaia. > > Someone(chris?) says "cpu: off" might be useful for eink device. > > What does wakeup: off do? Quote the Android ACQUIRE_CAUSES_WAKEUP flag: "Normal wake locks don't actually turn on the illumination. Instead, they cause the illumination to remain on once it turns on (e.g. from user activity). This flag will force the screen and/or keyboard to turn on immediately, when the WakeLock is acquired." But since we have API for controlling screen brightness we might not need this. > And what's the difference between "screen: on" and "screen: dim"? The screen is turned on, but has different brightness. Again we might not need this, but it specifies the minimum requirement of an app. Each apps just set their requirement and Gaia can decide the final brightness. > Also, I don't understand what the keyboard lock is supposed to do. I think it's the keyboard backlight. > > I think most of the power management code can be done is JS. > > Agreed. Can you please post a new proposed API? (It's actually two APIs; > one for privileged code managing the power state, and the other for content.) For privileged code: interface PowerManager { attribute double screenBrightness; attribute boolean screenEnabled; void sleep(); void powerOff(); void reboot(); nsIDOMMozWakeLock requestWakeLock(in ACString topic); }; We can implement content API on top of this.
> nsIDOMMozWakeLock requestWakeLock(in ACString topic); Is this not the function exposed to content? I expected we'd expose this to content (maybe privileged content only, but at least apps) and then have some API for our "chrome" to tell whether wake locks are held (see e.g. https://github.com/andreasgal/gaia/issues/167#issuecomment-3101666). But we can move this discussion into other bugs. Let me know if you need help with anything.
Created attachment 581165 [details] [diff] [review] 01
Created attachment 581166 [details] [diff] [review] 02
Created attachment 581167 [details] [diff] [review] 03
Created attachment 581168 [details] [diff] [review] 04
Created attachment 581169 [details] [diff] [review] 05
Created attachment 581170 [details] [diff] [review] 06
Sorry, this was for another bug.
(btw, are you using hg bzexport [1]? It makes exporting patch queues a lot easier. [1] http://blog.mozilla.com/ted/2010/09/07/bzexport-a-mercurial-extension/)
(In reply to Justin Lebar [:jlebar] from comment #15) > (btw, are you using hg bzexport [1]? It makes exporting patch queues a lot > easier. > > [1] http://blog.mozilla.com/ted/2010/09/07/bzexport-a-mercurial-extension/) I'm using Thinker's enhanced version :) http://www.codemud.net/~thinker/en/GinGin_CGI.py/show_id_doc/2
(In reply to Kan-Ru Chen [:kanru] from comment #6) > interface PowerManager { > attribute double screenBrightness; > attribute boolean screenEnabled; > > void sleep(); > void powerOff(); > void reboot(); > > nsIDOMMozWakeLock requestWakeLock(in ACString topic); > }; > > We can implement content API on top of this. Sorry for the bugspam, but was looking for this for Fennec. For reference, we have an XPCOM component for some screen brightness stuff in Android (not exposed to content): http://mxr.mozilla.org/mozilla-central/source/widget/nsIScreen.idl It would be nice to deprecate that if we can.... I don't think its used by anyone (currently) except XUL Fennec. But since there's no alternative yet, I'll probably use it for things like fullscreen video.
The documentation is done here * https://developer.mozilla.org/en-US/docs/DOM/window.navigator.mozPower * https://developer.mozilla.org/en-US/docs/DOM/window.navigator.requestWakeLock * https://developer.mozilla.org/en-US/docs/DOM/PowerManager
or
