Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 1 | Target |
| 2 | ====== |
| 3 | |
| 4 | |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 5 | .. class:: Target(connection_settings=None, platform=None, working_directory=None, executables_directory=None, connect=True, modules=None, load_default_modules=True, shell_prompt=DEFAULT_SHELL_PROMPT, conn_cls=None) |
| 6 | |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 7 | :class:`Target` is the primary interface to the remote device. All interactions |
| 8 | with the device are performed via a :class:`Target` instance, either |
| 9 | directly, or via its modules or a wrapper interface (such as an |
| 10 | :class:`Instrument`). |
| 11 | |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 12 | :param connection_settings: A ``dict`` that specifies how to connect to the remote |
Sergei Trofimov | 0125310 | 2016-12-07 18:03:44 +0000 | [diff] [blame] | 13 | device. Its contents depend on the specific :class:`Target` type (used see |
| 14 | :ref:`connection-types`\ ). |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 15 | |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 16 | :param platform: A :class:`Target` defines interactions at Operating System level. A |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 17 | :class:`Platform` describes the underlying hardware (such as CPUs |
| 18 | available). If a :class:`Platform` instance is not specified on |
| 19 | :class:`Target` creation, one will be created automatically and it will |
| 20 | dynamically probe the device to discover as much about the underlying |
Sergei Trofimov | 1ba7fbd | 2016-12-09 15:06:35 +0000 | [diff] [blame] | 21 | hardware as it can. See also :ref:`platform`\ . |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 22 | |
| 23 | :param working_directory: This is primary location for on-target file system |
| 24 | interactions performed by ``devlib``. This location *must* be readable and |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 25 | writable directly (i.e. without sudo) by the connection's user account. |
| 26 | It may or may not allow execution. This location will be created, |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 27 | if necessary, during ``setup()``. |
| 28 | |
| 29 | If not explicitly specified, this will be set to a default value |
| 30 | depending on the type of :class:`Target` |
| 31 | |
| 32 | :param executables_directory: This is the location to which ``devlib`` will |
| 33 | install executable binaries (either during ``setup()`` or via an |
| 34 | explicit ``install()`` call). This location *must* support execution |
| 35 | (obviously). It should also be possible to write to this location, |
| 36 | possibly with elevated privileges (i.e. on a rooted Linux target, it |
| 37 | should be possible to write here with sudo, but not necessarily directly |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 38 | by the connection's account). This location will be created, |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 39 | if necessary, during ``setup()``. |
| 40 | |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 41 | This location does *not* need to be same as the system's executables |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 42 | location. In fact, to prevent devlib from overwriting system's defaults, |
| 43 | it better if this is a separate location, if possible. |
| 44 | |
| 45 | If not explicitly specified, this will be set to a default value |
| 46 | depending on the type of :class:`Target` |
| 47 | |
| 48 | :param connect: Specifies whether a connections should be established to the |
| 49 | target. If this is set to ``False``, then ``connect()`` must be |
| 50 | explicitly called later on before the :class:`Target` instance can be |
| 51 | used. |
| 52 | |
| 53 | :param modules: a list of additional modules to be installed. Some modules will |
| 54 | try to install by default (if supported by the underlying target). |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 55 | Current default modules are ``hotplug``, ``cpufreq``, ``cpuidle``, |
Sergei Trofimov | 1ba7fbd | 2016-12-09 15:06:35 +0000 | [diff] [blame] | 56 | ``cgroups``, and ``hwmon`` (See :ref:`modules`\ ). |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 57 | |
| 58 | See modules documentation for more detail. |
| 59 | |
| 60 | :param load_default_modules: If set to ``False``, default modules listed |
| 61 | above will *not* attempt to load. This may be used to either speed up |
| 62 | target instantiation (probing for initializing modules takes a bit of time) |
| 63 | or if there is an issue with one of the modules on a particular device |
| 64 | (the rest of the modules will then have to be explicitly specified in |
| 65 | the ``modules``). |
| 66 | |
| 67 | :param shell_prompt: This is a regular expression that matches the shell |
| 68 | prompted on the target. This may be used by some modules that establish |
| 69 | auxiliary connections to a target over UART. |
| 70 | |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 71 | :param conn_cls: This is the type of connection that will be used to communicate |
| 72 | with the device. |
| 73 | |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 74 | .. attribute:: Target.core_names |
| 75 | |
| 76 | This is a list containing names of CPU cores on the target, in the order in |
| 77 | which they are index by the kernel. This is obtained via the underlying |
| 78 | :class:`Platform`. |
| 79 | |
| 80 | .. attribute:: Target.core_clusters |
| 81 | |
| 82 | Some devices feature heterogeneous core configurations (such as ARM |
| 83 | big.LITTLE). This is a list that maps CPUs onto underlying clusters. |
| 84 | (Usually, but not always, clusters correspond to groups of CPUs with the same |
| 85 | name). This is obtained via the underlying :class:`Platform`. |
| 86 | |
| 87 | .. attribute:: Target.big_core |
| 88 | |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 89 | This is the name of the cores that are the "big"s in an ARM big.LITTLE |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 90 | configuration. This is obtained via the underlying :class:`Platform`. |
| 91 | |
| 92 | .. attribute:: Target.little_core |
| 93 | |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 94 | This is the name of the cores that are the "little"s in an ARM big.LITTLE |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 95 | configuration. This is obtained via the underlying :class:`Platform`. |
| 96 | |
| 97 | .. attribute:: Target.is_connected |
| 98 | |
| 99 | A boolean value that indicates whether an active connection exists to the |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 100 | target device. |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 101 | |
| 102 | .. attribute:: Target.connected_as_root |
| 103 | |
| 104 | A boolean value that indicate whether the account that was used to connect to |
| 105 | the target device is "root" (uid=0). |
| 106 | |
| 107 | .. attribute:: Target.is_rooted |
| 108 | |
| 109 | A boolean value that indicates whether the connected user has super user |
| 110 | privileges on the devices (either is root, or is a sudoer). |
| 111 | |
| 112 | .. attribute:: Target.kernel_version |
| 113 | |
| 114 | The version of the kernel on the target device. This returns a |
| 115 | :class:`KernelVersion` instance that has separate ``version`` and ``release`` |
| 116 | fields. |
| 117 | |
| 118 | .. attribute:: Target.os_version |
| 119 | |
| 120 | This is a dict that contains a mapping of OS version elements to their |
| 121 | values. This mapping is OS-specific. |
| 122 | |
| 123 | .. attribute:: Target.cpuinfo |
| 124 | |
| 125 | This is a :class:`Cpuinfo` instance which contains parsed contents of |
| 126 | ``/proc/cpuinfo``. |
| 127 | |
| 128 | .. attribute:: Target.number_of_cpus |
| 129 | |
| 130 | The total number of CPU cores on the target device. |
| 131 | |
| 132 | .. attribute:: Target.config |
| 133 | |
| 134 | A :class:`KernelConfig` instance that contains parsed kernel config from the |
| 135 | target device. This may be ``None`` if kernel config could not be extracted. |
| 136 | |
| 137 | .. attribute:: Target.user |
| 138 | |
| 139 | The name of the user logged in on the target device. |
| 140 | |
| 141 | .. attribute:: Target.conn |
| 142 | |
| 143 | The underlying connection object. This will be ``None`` if an active |
| 144 | connection does not exist (e.g. if ``connect=False`` as passed on |
| 145 | initialization and ``connect()`` has not been called). |
| 146 | |
| 147 | .. note:: a :class:`Target` will automatically create a connection per |
| 148 | thread. This will always be set to the connection for the current |
| 149 | thread. |
| 150 | |
| 151 | .. method:: Target.connect([timeout]) |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 152 | |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 153 | Establish a connection to the target. It is usually not necessary to call |
| 154 | this explicitly, as a connection gets automatically established on |
| 155 | instantiation. |
| 156 | |
| 157 | .. method:: Target.disconnect() |
| 158 | |
| 159 | Disconnect from target, closing all active connections to it. |
| 160 | |
| 161 | .. method:: Target.get_connection([timeout]) |
| 162 | |
| 163 | Get an additional connection to the target. A connection can be used to |
| 164 | execute one blocking command at time. This will return a connection that can |
| 165 | be used to interact with a target in parallel while a blocking operation is |
| 166 | being executed. |
| 167 | |
| 168 | This should *not* be used to establish an initial connection; use |
| 169 | ``connect()`` instead. |
| 170 | |
| 171 | .. note:: :class:`Target` will automatically create a connection per |
| 172 | thread, so you don't normally need to use this explicitly in |
| 173 | threaded code. This is generally useful if you want to perform a |
| 174 | blocking operation (e.g. using ``background()``) while at the same |
| 175 | time doing something else in the same host-side thread. |
| 176 | |
| 177 | .. method:: Target.setup([executables]) |
| 178 | |
| 179 | This will perform an initial one-time set up of a device for devlib |
| 180 | interaction. This involves deployment of tools relied on the :class:`Target`, |
| 181 | creation of working locations on the device, etc. |
| 182 | |
| 183 | Usually, it is enough to call this method once per new device, as its effects |
| 184 | will persist across reboots. However, it is safe to call this method multiple |
| 185 | times. It may therefore be a good practice to always call it once at the |
| 186 | beginning of a script to ensure that subsequent interactions will succeed. |
| 187 | |
| 188 | Optionally, this may also be used to deploy additional tools to the device |
| 189 | by specifying a list of binaries to install in the ``executables`` parameter. |
| 190 | |
| 191 | .. method:: Target.reboot([hard [, connect, [timeout]]]) |
| 192 | |
| 193 | Reboot the target device. |
| 194 | |
| 195 | :param hard: A boolean value. If ``True`` a hard reset will be used instead |
| 196 | of the usual soft reset. Hard reset must be supported (usually via a |
| 197 | module) for this to work. Defaults to ``False``. |
| 198 | :param connect: A boolean value. If ``True``, a connection will be |
| 199 | automatically established to the target after reboot. Defaults to |
| 200 | ``True``. |
| 201 | :param timeout: If set, this will be used by various (platform-specific) |
| 202 | operations during reboot process to detect if the reboot has failed and |
| 203 | the device has hung. |
| 204 | |
| 205 | .. method:: Target.push(source, dest [, timeout]) |
| 206 | |
| 207 | Transfer a file from the host machine to the target device. |
| 208 | |
| 209 | :param source: path of to the file on the host |
| 210 | :param dest: path of to the file on the target |
| 211 | :param timeout: timeout (in seconds) for the transfer; if the transfer does |
| 212 | not complete within this period, an exception will be raised. |
| 213 | |
| 214 | .. method:: Target.pull(source, dest [, timeout]) |
| 215 | |
| 216 | Transfer a file from the target device to the host machine. |
| 217 | |
| 218 | :param source: path of to the file on the target |
| 219 | :param dest: path of to the file on the host |
| 220 | :param timeout: timeout (in seconds) for the transfer; if the transfer does |
| 221 | not complete within this period, an exception will be raised. |
| 222 | |
| 223 | .. method:: Target.execute(command [, timeout [, check_exit_code [, as_root]]]) |
| 224 | |
| 225 | Execute the specified command on the target device and return its output. |
| 226 | |
| 227 | :param command: The command to be executed. |
| 228 | :param timeout: Timeout (in seconds) for the execution of the command. If |
| 229 | specified, an exception will be raised if execution does not complete |
| 230 | with the specified period. |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 231 | :param check_exit_code: If ``True`` (the default) the exit code (on target) |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 232 | from execution of the command will be checked, and an exception will be |
| 233 | raised if it is not ``0``. |
| 234 | :param as_root: The command will be executed as root. This will fail on |
| 235 | unrooted targets. |
| 236 | |
| 237 | .. method:: Target.background(command [, stdout [, stderr [, as_root]]]) |
| 238 | |
| 239 | Execute the command on the target, invoking it via subprocess on the host. |
| 240 | This will return :class:`subprocess.Popen` instance for the command. |
| 241 | |
| 242 | :param command: The command to be executed. |
| 243 | :param stdout: By default, standard output will be piped from the subprocess; |
| 244 | this may be used to redirect it to an alternative file handle. |
| 245 | :param stderr: By default, standard error will be piped from the subprocess; |
| 246 | this may be used to redirect it to an alternative file handle. |
| 247 | :param as_root: The command will be executed as root. This will fail on |
| 248 | unrooted targets. |
| 249 | |
| 250 | .. note:: This **will block the connection** until the command completes. |
| 251 | |
| 252 | .. method:: Target.invoke(binary [, args [, in_directory [, on_cpus [, as_root [, timeout]]]]]) |
| 253 | |
| 254 | Execute the specified binary on target (must already be installed) under the |
| 255 | specified conditions and return the output. |
| 256 | |
| 257 | :param binary: binary to execute. Must be present and executable on the device. |
| 258 | :param args: arguments to be passed to the binary. The can be either a list or |
| 259 | a string. |
| 260 | :param in_directory: execute the binary in the specified directory. This must |
| 261 | be an absolute path. |
| 262 | :param on_cpus: taskset the binary to these CPUs. This may be a single ``int`` (in which |
| 263 | case, it will be interpreted as the mask), a list of ``ints``, in which |
| 264 | case this will be interpreted as the list of cpus, or string, which |
| 265 | will be interpreted as a comma-separated list of cpu ranges, e.g. |
| 266 | ``"0,4-7"``. |
| 267 | :param as_root: Specify whether the command should be run as root |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 268 | :param timeout: If this is specified and invocation does not terminate within this number |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 269 | of seconds, an exception will be raised. |
| 270 | |
Valentin Schneider | c8af995 | 2017-07-06 16:01:30 +0100 | [diff] [blame] | 271 | .. method:: Target.background_invoke(binary [, args [, in_directory [, on_cpus [, as_root ]]]]) |
| 272 | |
| 273 | Execute the specified binary on target (must already be installed) as a background |
| 274 | task, under the specified conditions and return the :class:`subprocess.Popen` |
| 275 | instance for the command. |
| 276 | |
| 277 | :param binary: binary to execute. Must be present and executable on the device. |
| 278 | :param args: arguments to be passed to the binary. The can be either a list or |
| 279 | a string. |
| 280 | :param in_directory: execute the binary in the specified directory. This must |
| 281 | be an absolute path. |
| 282 | :param on_cpus: taskset the binary to these CPUs. This may be a single ``int`` (in which |
| 283 | case, it will be interpreted as the mask), a list of ``ints``, in which |
| 284 | case this will be interpreted as the list of cpus, or string, which |
| 285 | will be interpreted as a comma-separated list of cpu ranges, e.g. |
| 286 | ``"0,4-7"``. |
| 287 | :param as_root: Specify whether the command should be run as root |
| 288 | |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 289 | .. method:: Target.kick_off(command [, as_root]) |
| 290 | |
| 291 | Kick off the specified command on the target and return immediately. Unlike |
| 292 | ``background()`` this will not block the connection; on the other hand, there |
| 293 | is not way to know when the command finishes (apart from calling ``ps()``) |
| 294 | or to get its output (unless its redirected into a file that can be pulled |
| 295 | later as part of the command). |
| 296 | |
| 297 | :param command: The command to be executed. |
| 298 | :param as_root: The command will be executed as root. This will fail on |
| 299 | unrooted targets. |
| 300 | |
| 301 | .. method:: Target.read_value(path [,kind]) |
| 302 | |
| 303 | Read the value from the specified path. This is primarily intended for |
| 304 | sysfs/procfs/debugfs etc. |
| 305 | |
| 306 | :param path: file to read |
| 307 | :param kind: Optionally, read value will be converted into the specified |
| 308 | kind (which should be a callable that takes exactly one parameter). |
| 309 | |
| 310 | .. method:: Target.read_int(self, path) |
| 311 | |
| 312 | Equivalent to ``Target.read_value(path, kind=devlab.utils.types.integer)`` |
| 313 | |
| 314 | .. method:: Target.read_bool(self, path) |
| 315 | |
| 316 | Equivalent to ``Target.read_value(path, kind=devlab.utils.types.boolean)`` |
| 317 | |
| 318 | .. method:: Target.write_value(path, value [, verify]) |
| 319 | |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 320 | Write the value to the specified path on the target. This is primarily |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 321 | intended for sysfs/procfs/debugfs etc. |
| 322 | |
| 323 | :param path: file to write into |
| 324 | :param value: value to be written |
| 325 | :param verify: If ``True`` (the default) the value will be read back after |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 326 | it is written to make sure it has been written successfully. This due to |
Sergei Trofimov | 4e6afe9 | 2015-10-09 09:30:04 +0100 | [diff] [blame] | 327 | some sysfs entries silently failing to set the written value without |
| 328 | returning an error code. |
| 329 | |
| 330 | .. method:: Target.reset() |
| 331 | |
| 332 | Soft reset the target. Typically, this means executing ``reboot`` on the |
| 333 | target. |
| 334 | |
| 335 | .. method:: Target.check_responsive() |
| 336 | |
| 337 | Returns ``True`` if the target appears to be responsive and ``False`` |
| 338 | otherwise. |
| 339 | |
| 340 | .. method:: Target.kill(pid[, signal[, as_root]]) |
| 341 | |
| 342 | Kill a process on the target. |
| 343 | |
| 344 | :param pid: PID of the process to be killed. |
| 345 | :param signal: Signal to be used to kill the process. Defaults to |
| 346 | ``signal.SIGTERM``. |
| 347 | :param as_root: If set to ``True``, kill will be issued as root. This will |
| 348 | fail on unrooted targets. |
| 349 | |
| 350 | .. method:: Target.killall(name[, signal[, as_root]]) |
| 351 | |
| 352 | Kill all processes with the specified name on the target. Other parameters |
| 353 | are the same as for ``kill()``. |
| 354 | |
| 355 | .. method:: Target.get_pids_of(name) |
| 356 | |
| 357 | Return a list of PIDs of all running instances of the specified process. |
| 358 | |
| 359 | .. method:: Target.ps() |
| 360 | |
| 361 | Return a list of :class:`PsEntry` instances for all running processes on the |
| 362 | system. |
| 363 | |
| 364 | .. method:: Target.file_exists(self, filepath) |
| 365 | |
| 366 | Returns ``True`` if the specified path exists on the target and ``False`` |
| 367 | otherwise. |
| 368 | |
| 369 | .. method:: Target.list_file_systems() |
| 370 | |
| 371 | Lists file systems mounted on the target. Returns a list of |
| 372 | :class:`FstabEntry`\ s. |
| 373 | |
| 374 | .. method:: Target.list_directory(path[, as_root]) |
| 375 | |
| 376 | List (optionally, as root) the contents of the specified directory. Returns a |
| 377 | list of strings. |
| 378 | |
| 379 | |
| 380 | .. method:: Target.get_workpath(self, path) |
| 381 | |
| 382 | Convert the specified path to an absolute path relative to |
| 383 | ``working_directory`` on the target. This is a shortcut for |
| 384 | ``t.path.join(t.working_directory, path)`` |
| 385 | |
| 386 | .. method:: Target.tempfile([prefix [, suffix]]) |
| 387 | |
| 388 | Get a path to a temporary file (optionally, with the specified prefix and/or |
| 389 | suffix) on the target. |
| 390 | |
| 391 | .. method:: Target.remove(path[, as_root]) |
| 392 | |
| 393 | Delete the specified path on the target. Will work on files and directories. |
| 394 | |
| 395 | .. method:: Target.core_cpus(core) |
| 396 | |
| 397 | Return a list of numeric cpu IDs corresponding to the specified core name. |
| 398 | |
| 399 | .. method:: Target.list_online_cpus([core]) |
| 400 | |
| 401 | Return a list of numeric cpu IDs for all online CPUs (optionally, only for |
| 402 | CPUs corresponding to the specified core). |
| 403 | |
| 404 | .. method:: Target.list_offline_cpus([core]) |
| 405 | |
| 406 | Return a list of numeric cpu IDs for all offline CPUs (optionally, only for |
| 407 | CPUs corresponding to the specified core). |
| 408 | |
| 409 | .. method:: Target.getenv(variable) |
| 410 | |
| 411 | Return the value of the specified environment variable on the device |
| 412 | |
| 413 | .. method:: Target.capture_screen(filepath) |
| 414 | |
| 415 | Take a screenshot on the device and save it to the specified file on the |
| 416 | host. This may not be supported by the target. |
| 417 | |
| 418 | .. method:: Target.install(filepath[, timeout[, with_name]]) |
| 419 | |
| 420 | Install an executable on the device. |
| 421 | |
| 422 | :param filepath: path to the executable on the host |
| 423 | :param timeout: Optional timeout (in seconds) for the installation |
| 424 | :param with_name: This may be used to rename the executable on the target |
| 425 | |
| 426 | .. method:: Target.uninstall(name) |
| 427 | |
| 428 | Uninstall the specified executable from the target |
| 429 | |
| 430 | .. method:: Target.get_installed(name) |
| 431 | |
| 432 | Return the full installation path on the target for the specified executable, |
| 433 | or ``None`` if the executable is not installed. |
| 434 | |
| 435 | .. method:: Target.which(name) |
| 436 | |
| 437 | Alias for ``get_installed()`` |
| 438 | |
| 439 | .. method:: Target.is_installed(name) |
| 440 | |
| 441 | Returns ``True`` if an executable with the specified name is installed on the |
| 442 | target and ``False`` other wise. |
| 443 | |
Sergei Trofimov | c4784e0 | 2016-07-14 11:15:08 +0100 | [diff] [blame] | 444 | .. method:: Target.extract(path, dest=None) |
| 445 | |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 446 | Extracts the specified archive/file and returns the path to the extracted |
Sergei Trofimov | c4784e0 | 2016-07-14 11:15:08 +0100 | [diff] [blame] | 447 | contents. The extraction method is determined based on the file extension. |
| 448 | ``zip``, ``tar``, ``gzip``, and ``bzip2`` are supported. |
| 449 | |
| 450 | :param dest: Specified an on-target destination directory (which must exist) |
Marc Bonnici | 1fd5636 | 2017-01-10 15:35:21 +0000 | [diff] [blame] | 451 | for the extracted contents. |
Sergei Trofimov | c4784e0 | 2016-07-14 11:15:08 +0100 | [diff] [blame] | 452 | |
| 453 | Returns the path to the extracted contents. In case of files (gzip and |
| 454 | bzip2), the path to the decompressed file is returned; for archives, the |
| 455 | path to the directory with the archive's contents is returned. |
Marc Bonnici | 5b99c16 | 2017-08-09 10:56:01 +0100 | [diff] [blame] | 456 | |
| 457 | |
| 458 | Android Target |
| 459 | --------------- |
| 460 | |
| 461 | .. class:: AndroidTarget(connection_settings=None, platform=None, working_directory=None, executables_directory=None, connect=True, modules=None, load_default_modules=True, shell_prompt=DEFAULT_SHELL_PROMPT, conn_cls=AdbConnection, package_data_directory="/data/data") |
| 462 | |
| 463 | :class:`AndroidTarget` is a subclass of :class:`Target` with additional features specific to a device running Android. |
| 464 | |
| 465 | :param package_data_directory: This is the location of the data stored |
| 466 | for installed Android packages on the device. |
| 467 | |
| 468 | .. method:: AndroidTarget.set_rotation(rotation) |
| 469 | |
| 470 | Specify an integer representing the desired screen rotation with the |
| 471 | following mappings: Natural: ``0``, Rotated Left: ``1``, Inverted : ``2`` |
| 472 | and Rotated Right : ``3``. |
| 473 | |
| 474 | .. method:: AndroidTarget.get_rotation(rotation) |
| 475 | |
| 476 | Returns an integer value representing the orientation of the devices |
| 477 | screen. ``0`` : Natural, ``1`` : Rotated Left, ``2`` : Inverted |
| 478 | and ``3`` : Rotated Right. |
| 479 | |
| 480 | .. method:: AndroidTarget.set_natural_rotation() |
| 481 | |
| 482 | Sets the screen orientation of the device to its natural (0 degrees) |
| 483 | orientation. |
| 484 | |
| 485 | .. method:: AndroidTarget.set_left_rotation() |
| 486 | |
| 487 | Sets the screen orientation of the device to 90 degrees. |
| 488 | |
| 489 | .. method:: AndroidTarget.set_inverted_rotation() |
| 490 | |
| 491 | Sets the screen orientation of the device to its inverted (180 degrees) |
| 492 | orientation. |
| 493 | |
| 494 | .. method:: AndroidTarget.set_right_rotation() |
| 495 | |
| 496 | Sets the screen orientation of the device to 270 degrees. |
| 497 | |
| 498 | .. method:: AndroidTarget.set_auto_rotation(autorotate) |
| 499 | |
| 500 | Specify a boolean value for whether the devices auto-rotation should |
| 501 | be enabled. |
| 502 | |
| 503 | .. method:: AndroidTarget.get_auto_rotation() |
| 504 | |
| 505 | Returns ``True`` if the targets auto rotation is currently enabled and |
| 506 | ``False`` otherwise. |
| 507 | |
| 508 | .. method:: AndroidTarget.set_airplane_mode(mode) |
| 509 | |
| 510 | Specify a boolean value for whether the device should be in airplane mode. |
| 511 | |
| 512 | .. note:: Requires the device to be rooted if the device is running Android 7+. |
| 513 | |
| 514 | .. method:: AndroidTarget.get_airplane_mode() |
| 515 | |
| 516 | Returns ``True`` if the target is currently in airplane mode and |
| 517 | ``False`` otherwise. |
| 518 | |
| 519 | .. method:: AndroidTarget.set_brightness(value) |
| 520 | |
| 521 | Sets the devices screen brightness to a specified integer between ``0`` and |
| 522 | ``255``. |
| 523 | |
| 524 | .. method:: AndroidTarget.get_brightness() |
| 525 | |
| 526 | Returns an integer between ``0`` and ``255`` representing the devices |
| 527 | current screen brightness. |
| 528 | |
| 529 | .. method:: AndroidTarget.set_auto_brightness(auto_brightness) |
| 530 | |
| 531 | Specify a boolean value for whether the devices auto brightness |
| 532 | should be enabled. |
| 533 | |
| 534 | .. method:: AndroidTarget.get_auto_brightness() |
| 535 | |
| 536 | Returns ``True`` if the targets auto brightness is currently |
| 537 | enabled and ``False`` otherwise. |
| 538 | |
| 539 | .. method:: AndroidTarget.ensure_screen_is_off() |
| 540 | |
| 541 | Checks if the devices screen is on and if so turns it off. |
| 542 | |
| 543 | .. method:: AndroidTarget.ensure_screen_is_on() |
| 544 | |
| 545 | Checks if the devices screen is off and if so turns it on. |
| 546 | |
| 547 | .. method:: AndroidTarget.is_screen_on() |
| 548 | |
| 549 | Returns ``True`` if the targets screen is currently on and ``False`` |
| 550 | otherwise. |
| 551 | |
| 552 | .. method:: AndroidTarget.homescreen() |
| 553 | |
| 554 | Returns the device to its home screen. |
| 555 | |
| 556 | .. method:: AndroidTarget.swipe_to_unlock(direction="diagonal") |
| 557 | |
| 558 | Performs a swipe input on the device to try and unlock the device. |
| 559 | A direction of ``"horizontal"``, ``"vertical"`` or ``"diagonal"`` |
| 560 | can be supplied to specify in which direction the swipe should be |
| 561 | performed. By default ``"diagonal"`` will be used to try and |
| 562 | support the majority of newer devices. |