devlib/target: Enable screen stay-on mode:

Adds the ability to set the android global setting
``stay_on_while_plugged_in``.

This setting has 4 main modes:
- 0: never stay on
- 1: stay on when plugged in to AC charger
- 2: stay on when plugged in to USB charger
- 4: stay on when wirelessly charged

These values can be OR-ed together to produce combinations.

devlib/target.py

@@ -1713,6 +1713,10 @@ class AndroidTarget(Target):
         if verify and not self.is_screen_on():
              raise TargetStableError('Display cannot be turned on.')
 
+    def ensure_screen_is_on_and_stays(self, verify=True, mode=7):
+        self.ensure_screen_is_on(verify=verify)
+        self.set_stay_on_mode(mode)
+
     def ensure_screen_is_off(self, verify=True):
         # Allow 2 attempts to help with cases of ambient display modes
         # where the first attempt will switch the display fully on.
@@ -1756,6 +1760,10 @@ class AndroidTarget(Target):
         cmd = 'settings get global airplane_mode_on'
         return boolean(self.execute(cmd).strip())
 
+    def get_stay_on_mode(self):
+        cmd = 'settings get global stay_on_while_plugged_in'
+        return int(self.execute(cmd).strip())
+
     def set_airplane_mode(self, mode):
         root_required = self.get_sdk_version() > 23
         if root_required and not self.is_rooted:
@@ -1801,6 +1809,18 @@ class AndroidTarget(Target):
         cmd = 'settings put system user_rotation {}'
         self.execute(cmd.format(rotation))
 
+    def set_stay_on_never(self):
+        self.set_stay_on_mode(0)
+
+    def set_stay_on_while_powered(self):
+        self.set_stay_on_mode(7)
+
+    def set_stay_on_mode(self, mode):
+        if not 0 <= mode <= 7:
+            raise ValueError('Screen stay on mode must be between 0 and 7')
+        cmd = 'settings put global stay_on_while_plugged_in {}'
+        self.execute(cmd.format(mode))
+
     def open_url(self, url, force_new=False):
         """
         Start a view activity by specifying an URL

doc/target.rst

@@ -672,6 +672,26 @@ Android Target
    Returns ``True`` if the targets auto brightness is currently
    enabled and ``False`` otherwise.
 
+.. method:: AndroidTarget.set_stay_on_never()
+
+   Sets the stay-on mode to ``0``, where the screen will turn off
+   as standard after the timeout.
+
+.. method:: AndroidTarget.set_stay_on_while_powered()
+
+   Sets the stay-on mode to ``7``, where the screen will stay on
+   while the device is charging
+
+.. method:: AndroidTarget.set_stay_on_mode(mode)
+
+   Sets the stay-on mode to the specified number between ``0`` and
+   ``7`` (inclusive).
+
+.. method:: AndroidTarget.get_stay_on_mode()
+
+   Returns an integer between ``0`` and ``7`` representing the current
+   stay-on mode of the device. 
+
 .. method:: AndroidTarget.ensure_screen_is_off(verify=True)
 
    Checks if the devices screen is on and if so turns it off.
@@ -685,6 +705,11 @@ Android Target
    If ``verify`` is set to ``True`` then a ``TargetStableError``
    will be raise if the display cannot be turned on.
 
+.. method:: AndroidTarget.ensure_screen_is_on_and_stays(verify=True, mode=7)
+
+   Calls ``AndroidTarget.ensure_screen_is_on(verify)`` then additionally
+   sets the screen stay on mode to ``mode``.
+
 .. method:: AndroidTarget.is_screen_on()
 
    Returns ``True`` if the targets screen is currently on and ``False``