adb_commands.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421
  1. # Copyright 2014 Google Inc. All rights reserved.
  2. #
  3. # Licensed under the Apache License, Version 2.0 (the "License");
  4. # you may not use this file except in compliance with the License.
  5. # You may obtain a copy of the License at
  6. #
  7. # http://www.apache.org/licenses/LICENSE-2.0
  8. #
  9. # Unless required by applicable law or agreed to in writing, software
  10. # distributed under the License is distributed on an "AS IS" BASIS,
  11. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. # See the License for the specific language governing permissions and
  13. # limitations under the License.
  14. """A libusb1-based ADB reimplementation.
  15. ADB was giving us trouble with its client/server architecture, which is great
  16. for users and developers, but not so great for reliable scripting. This will
  17. allow us to more easily catch errors as Python exceptions instead of checking
  18. random exit codes, and all the other great benefits from not going through
  19. subprocess and a network socket.
  20. All timeouts are in milliseconds.
  21. """
  22. import io
  23. import os
  24. import socket
  25. import posixpath
  26. from adb import adb_protocol
  27. from adb import common
  28. from adb import filesync_protocol
  29. # From adb.h
  30. CLASS = 0xFF
  31. SUBCLASS = 0x42
  32. PROTOCOL = 0x01
  33. # pylint: disable=invalid-name
  34. DeviceIsAvailable = common.InterfaceMatcher(CLASS, SUBCLASS, PROTOCOL)
  35. try:
  36. # Imported locally to keep compatibility with previous code.
  37. from adb.sign_m2crypto import M2CryptoSigner
  38. except ImportError:
  39. # Ignore this error when M2Crypto is not installed, there are other options.
  40. pass
  41. class AdbCommands(object):
  42. """Exposes adb-like methods for use.
  43. Some methods are more-pythonic and/or have more options.
  44. """
  45. protocol_handler = adb_protocol.AdbMessage
  46. filesync_handler = filesync_protocol.FilesyncProtocol
  47. def __init__(self):
  48. self.__reset()
  49. def __reset(self):
  50. self.build_props = None
  51. self._handle = None
  52. self._device_state = None
  53. # Connection table tracks each open AdbConnection objects per service type for program functions
  54. # that choose to persist an AdbConnection object for their functionality, using
  55. # self._get_service_connection
  56. self._service_connections = {}
  57. def _get_service_connection(self, service, service_command=None, create=True, timeout_ms=None):
  58. """
  59. Based on the service, get the AdbConnection for that service or create one if it doesnt exist
  60. :param service:
  61. :param service_command: Additional service parameters to append
  62. :param create: If False, dont create a connection if it does not exist
  63. :return:
  64. """
  65. connection = self._service_connections.get(service, None)
  66. if connection:
  67. return connection
  68. if not connection and not create:
  69. return None
  70. if service_command:
  71. destination_str = b'%s:%s' % (service, service_command)
  72. else:
  73. destination_str = service
  74. connection = self.protocol_handler.Open(
  75. self._handle, destination=destination_str, timeout_ms=timeout_ms)
  76. self._service_connections.update({service: connection})
  77. return connection
  78. def ConnectDevice(self, port_path=None, serial=None, default_timeout_ms=None, **kwargs):
  79. """Convenience function to setup a transport handle for the adb device from
  80. usb path or serial then connect to it.
  81. Args:
  82. port_path: The filename of usb port to use.
  83. serial: The serial number of the device to use.
  84. default_timeout_ms: The default timeout in milliseconds to use.
  85. kwargs: handle: Device handle to use (instance of common.TcpHandle or common.UsbHandle)
  86. banner: Connection banner to pass to the remote device
  87. rsa_keys: List of AuthSigner subclass instances to be used for
  88. authentication. The device can either accept one of these via the Sign
  89. method, or we will send the result of GetPublicKey from the first one
  90. if the device doesn't accept any of them.
  91. auth_timeout_ms: Timeout to wait for when sending a new public key. This
  92. is only relevant when we send a new public key. The device shows a
  93. dialog and this timeout is how long to wait for that dialog. If used
  94. in automation, this should be low to catch such a case as a failure
  95. quickly; while in interactive settings it should be high to allow
  96. users to accept the dialog. We default to automation here, so it's low
  97. by default.
  98. If serial specifies a TCP address:port, then a TCP connection is
  99. used instead of a USB connection.
  100. """
  101. # If there isnt a handle override (used by tests), build one here
  102. if 'handle' in kwargs:
  103. self._handle = kwargs.pop('handle')
  104. else:
  105. # if necessary, convert serial to a unicode string
  106. if isinstance(serial, (bytes, bytearray)):
  107. serial = serial.decode('utf-8')
  108. if serial and ':' in serial:
  109. self._handle = common.TcpHandle(serial, timeout_ms=default_timeout_ms)
  110. elif 'tty' in serial:
  111. self._handle = common.SerialHandle(serial, timeout_ms=default_timeout_ms)
  112. else:
  113. self._handle = common.UsbHandle.FindAndOpen(
  114. DeviceIsAvailable, port_path=port_path, serial=serial,
  115. timeout_ms=default_timeout_ms)
  116. self._Connect(**kwargs)
  117. return self
  118. def Close(self):
  119. for conn in list(self._service_connections.values()):
  120. if conn:
  121. try:
  122. conn.Close()
  123. except:
  124. pass
  125. if self._handle:
  126. self._handle.Close()
  127. self.__reset()
  128. def _Connect(self, banner=None, **kwargs):
  129. """Connect to the device.
  130. Args:
  131. banner: See protocol_handler.Connect.
  132. **kwargs: See protocol_handler.Connect and adb_commands.ConnectDevice for kwargs.
  133. Includes handle, rsa_keys, and auth_timeout_ms.
  134. Returns:
  135. An instance of this class if the device connected successfully.
  136. """
  137. if not banner:
  138. banner = socket.gethostname().encode()
  139. conn_str = self.protocol_handler.Connect(self._handle, banner=banner, **kwargs)
  140. # Remove banner and colons after device state (state::banner)
  141. parts = conn_str.split(b'::')
  142. self._device_state = parts[0]
  143. # Break out the build prop info
  144. self.build_props = str(parts[1].split(b';'))
  145. return True
  146. @classmethod
  147. def Devices(cls):
  148. """Get a generator of UsbHandle for devices available."""
  149. return common.UsbHandle.FindDevices(DeviceIsAvailable)
  150. def GetState(self):
  151. return self._device_state
  152. def Install(self, apk_path, destination_dir='', replace_existing=True,
  153. grant_permissions=False, timeout_ms=None, transfer_progress_callback=None):
  154. """Install an apk to the device.
  155. Doesn't support verifier file, instead allows destination directory to be
  156. overridden.
  157. Args:
  158. apk_path: Local path to apk to install.
  159. destination_dir: Optional destination directory. Use /system/app/ for
  160. persistent applications.
  161. replace_existing: whether to replace existing application
  162. grant_permissions: If True, grant all permissions to the app specified in its manifest
  163. timeout_ms: Expected timeout for pushing and installing.
  164. transfer_progress_callback: callback method that accepts filename, bytes_written and total_bytes of APK transfer
  165. Returns:
  166. The pm install output.
  167. """
  168. if not destination_dir:
  169. destination_dir = '/data/local/tmp/'
  170. basename = os.path.basename(apk_path)
  171. destination_path = posixpath.join(destination_dir, basename)
  172. self.Push(apk_path, destination_path, timeout_ms=timeout_ms, progress_callback=transfer_progress_callback)
  173. cmd = ['pm install']
  174. if grant_permissions:
  175. cmd.append('-g')
  176. if replace_existing:
  177. cmd.append('-r')
  178. cmd.append('"{}"'.format(destination_path))
  179. ret = self.Shell(' '.join(cmd), timeout_ms=timeout_ms)
  180. # Remove the apk
  181. rm_cmd = ['rm', destination_path]
  182. rmret = self.Shell(' '.join(rm_cmd), timeout_ms=timeout_ms)
  183. return ret
  184. def Uninstall(self, package_name, keep_data=False, timeout_ms=None):
  185. """Removes a package from the device.
  186. Args:
  187. package_name: Package name of target package.
  188. keep_data: whether to keep the data and cache directories
  189. timeout_ms: Expected timeout for pushing and installing.
  190. Returns:
  191. The pm uninstall output.
  192. """
  193. cmd = ['pm uninstall']
  194. if keep_data:
  195. cmd.append('-k')
  196. cmd.append('"%s"' % package_name)
  197. return self.Shell(' '.join(cmd), timeout_ms=timeout_ms)
  198. def Push(self, source_file, device_filename, mtime='0', timeout_ms=None, progress_callback=None, st_mode=None):
  199. """Push a file or directory to the device.
  200. Args:
  201. source_file: Either a filename, a directory or file-like object to push to
  202. the device.
  203. device_filename: Destination on the device to write to.
  204. mtime: Optional, modification time to set on the file.
  205. timeout_ms: Expected timeout for any part of the push.
  206. st_mode: stat mode for filename
  207. progress_callback: callback method that accepts filename, bytes_written and total_bytes,
  208. total_bytes will be -1 for file-like objects
  209. """
  210. if isinstance(source_file, str):
  211. if os.path.isdir(source_file):
  212. self.Shell("mkdir " + device_filename)
  213. for f in os.listdir(source_file):
  214. self.Push(os.path.join(source_file, f), device_filename + '/' + f,
  215. progress_callback=progress_callback)
  216. return
  217. source_file = open(source_file, "rb")
  218. with source_file:
  219. connection = self.protocol_handler.Open(
  220. self._handle, destination=b'installer:', timeout_ms=timeout_ms)
  221. kwargs={}
  222. if st_mode is not None:
  223. kwargs['st_mode'] = st_mode
  224. self.filesync_handler.Push(connection, source_file, device_filename,
  225. mtime=int(mtime), progress_callback=progress_callback, **kwargs)
  226. connection.Close()
  227. def Pull(self, device_filename, dest_file=None, timeout_ms=None, progress_callback=None):
  228. """Pull a file from the device.
  229. Args:
  230. device_filename: Filename on the device to pull.
  231. dest_file: If set, a filename or writable file-like object.
  232. timeout_ms: Expected timeout for any part of the pull.
  233. progress_callback: callback method that accepts filename, bytes_written and total_bytes,
  234. total_bytes will be -1 for file-like objects
  235. Returns:
  236. The file data if dest_file is not set. Otherwise, True if the destination file exists
  237. """
  238. if not dest_file:
  239. dest_file = io.BytesIO()
  240. elif isinstance(dest_file, str):
  241. dest_file = open(dest_file, 'wb')
  242. elif isinstance(dest_file, file):
  243. pass
  244. else:
  245. raise ValueError("destfile is of unknown type")
  246. conn = self.protocol_handler.Open(
  247. self._handle, destination=b'installer:', timeout_ms=timeout_ms)
  248. self.filesync_handler.Pull(conn, device_filename, dest_file, progress_callback)
  249. conn.Close()
  250. if isinstance(dest_file, io.BytesIO):
  251. return dest_file.getvalue()
  252. else:
  253. dest_file.close()
  254. if hasattr(dest_file, 'name'):
  255. return os.path.exists(dest_file.name)
  256. # We don't know what the path is, so we just assume it exists.
  257. return True
  258. def Stat(self, device_filename):
  259. """Get a file's stat() information."""
  260. connection = self.protocol_handler.Open(self._handle, destination=b'installer:')
  261. mode, size, mtime = self.filesync_handler.Stat(
  262. connection, device_filename)
  263. connection.Close()
  264. return mode, size, mtime
  265. def List(self, device_path):
  266. """Return a directory listing of the given path.
  267. Args:
  268. device_path: Directory to list.
  269. """
  270. connection = self.protocol_handler.Open(self._handle, destination=b'installer:')
  271. listing = self.filesync_handler.List(connection, device_path)
  272. connection.Close()
  273. return listing
  274. def Reboot(self, destination=b''):
  275. """Reboot the device.
  276. Args:
  277. destination: Specify 'bootloader' for fastboot.
  278. """
  279. self.protocol_handler.Open(self._handle, b'reboot:%s' % destination)
  280. def RebootBootloader(self):
  281. """Reboot device into fastboot."""
  282. self.Reboot(b'bootloader')
  283. def Remount(self):
  284. """Remount / as read-write."""
  285. return self.protocol_handler.Command(self._handle, service=b'remount')
  286. def Root(self):
  287. """Restart adbd as root on the device."""
  288. return self.protocol_handler.Command(self._handle, service=b'root')
  289. def EnableVerity(self):
  290. """Re-enable dm-verity checking on userdebug builds"""
  291. return self.protocol_handler.Command(self._handle, service=b'enable-verity')
  292. def DisableVerity(self):
  293. """Disable dm-verity checking on userdebug builds"""
  294. return self.protocol_handler.Command(self._handle, service=b'disable-verity')
  295. def Shell(self, command, timeout_ms=None):
  296. """Run command on the device, returning the output.
  297. Args:
  298. command: Shell command to run
  299. timeout_ms: Maximum time to allow the command to run.
  300. """
  301. return self.protocol_handler.Command(
  302. self._handle, service=b'shell', command=command,
  303. timeout_ms=timeout_ms)
  304. def StreamingShell(self, command, timeout_ms=None):
  305. """Run command on the device, yielding each line of output.
  306. Args:
  307. command: Command to run on the target.
  308. timeout_ms: Maximum time to allow the command to run.
  309. Yields:
  310. The responses from the shell command.
  311. """
  312. return self.protocol_handler.StreamingCommand(
  313. self._handle, service=b'shell', command=command,
  314. timeout_ms=timeout_ms)
  315. def Logcat(self, options, timeout_ms=None):
  316. """Run 'shell logcat' and stream the output to stdout.
  317. Args:
  318. options: Arguments to pass to 'logcat'.
  319. timeout_ms: Maximum time to allow the command to run.
  320. """
  321. return self.StreamingShell('logcat %s' % options, timeout_ms)
  322. def InteractiveShell(self, cmd=None, strip_cmd=True, delim=None, strip_delim=True):
  323. """Get stdout from the currently open interactive shell and optionally run a command
  324. on the device, returning all output.
  325. Args:
  326. cmd: Optional. Command to run on the target.
  327. strip_cmd: Optional (default True). Strip command name from stdout.
  328. delim: Optional. Delimiter to look for in the output to know when to stop expecting more output
  329. (usually the shell prompt)
  330. strip_delim: Optional (default True): Strip the provided delimiter from the output
  331. Returns:
  332. The stdout from the shell command.
  333. """
  334. conn = self._get_service_connection(b'shell:')
  335. return self.protocol_handler.InteractiveShellCommand(
  336. conn, cmd=cmd, strip_cmd=strip_cmd,
  337. delim=delim, strip_delim=strip_delim)