Android Debug Bridge (adb) является мощной утилитой командной строки, работающей на хосте отладки (обычно компьютер, на котором Вы пишете и отлаживаете ПО для Android). ADB позволяет обмениваться данными с запущенным эмулятором Android или реальным подключенным (через USB, сеть Wi-Fi) устройством Android (планшет, телефон). Здесь и далее перевод документации [1].

ADB работает по технологии клиент-сервер, и включает в себя 3 компонента:

• Клиент, который работает на Вашем хосте отладки. Вы можете вызвать клиента из командной строки, если запустите команду adb. Другие инструменты Android, такие как DDMS и плагин ADT, также создают клиентов adb.
• Сервер, который запущен как фоновый процесс на хосте разработки. Сервер управляет обменом данными между клиентом и демоном, работающем на эмуляторе или устройстве Android.
• Демон (служба), которая запущена как фоновый процесс на каждом экземпляре эмулятора или подключенном устройстве Android.

Утилиту adb Вы можете найти в каталоге [sdk]/platform-tools/ (на компьютерах с операционной системой Windows это обычно папка c:\Program Files\Android\android-studio\sdk\platform-tools\).

Сразу после запуска клиент adb сначала проверяет, запущен ли процесс сервера adb. Если нет, то клиент adb запускает процесс сервера. Когда стартует сервер, он запускает прослушивание локального порта TCP 5037 (на адресе localhost), и считывает с него поступающие команды от клиентов adb — все клиенты adb используют порт 5037 для обмена данными с сервером adb.

Затем сервер устанавливает соединения со всеми запущенными экземплярами эмуляторов и/или устройств. Он находит эмуляторы и устройства путем сканирования нечетных портов в диапазоне 5555 .. 5585, этот диапазон используется для эмуляторов/устройств. Когда сервер находит демона adb, он устанавливает с ним соединение по этому порту. Имейте в виду, что каждый экземпляр эмулятора/устройства занимает пару последовательных портов — четный номер порта для подключения консоли и нечетный номер порта для соединений adb, например:

Emulator 1, console: 5554
Emulator 1, adb: 5555
Emulator 2, console: 5556
Emulator 2, adb: 5557
...

Как здесь показано, экземпляр эмулятора, подключенного к adb через порт 5555 тот же самый, что прослушивает порт консоли 5554.

Как только сервер установил соединения со всеми экземплярами эмуляторов, Вы можете использовать команды adb для получения доступа к этим эмуляторам. Поскольку сервер обслуживает соединения к эмуляторам/устройствам и обрабатывает команды от множества клиентов adb, Вы можете управлять любым эмулятором/устройством от любого клиента (или из скрипта).

Примечание: когда Вы подключаете к устройство, на котором работает Android 4.2.2 или более новая версия, к Вашему компьютеру, система покажет диалог, запрашивающий подтвердить ключ RSA, который позволит отлаживать программы Android через этот компьютер (хост отладки). Этот механизм безопасности защищает устройства пользователя, потому что он гарантирует, что отладка через USB и другие команды adb не могут быть выполнены, пока Вы явно не разблокируете устройство, выбрав подтверждение в этом диалоге. Для поддержки этой возможности требуется adb версии 1.0.31 (доступно в SDK Platform-tools r16.0.1 и более свежих версиях) при отладке на устройстве с работающей системой Android 4.2.2 или более свежей.

[Синтаксис ADB]

Вы можете вызвать команды adb из командной строки хоста отладки или из скрипта. Общий вид команды adb следующий:

adb [-d|-e|-s < serialNumber >] < command > 

Если на хосте отладки работает только один эмулятор, или подключено только одно устройство, то команда adb подключится к нему по умолчанию. Если работает несколько эмуляторов или подключено несколько устройств, то нужно указывать опции -d, -e или -s, чтобы указать целевое устройство для подключения - кому предназначена команда command.

[Команды ADB]

В таблице ниже перечислены все поддерживаемые команды adb, а также объясняется их назначение и использование.

Таблица 1. Доступные команды adb.

[Опрос имеющихся эмуляторов/устройств]

Перед тем, как запускать команды adb, полезно знать, какие экземпляры эмулятора/устройства подключены к серверу adb. Вы можете сгенерировать список подключенных эмуляторов/устройств, используя команду devices:

adb devices 

В ответ adb распечатает информацию состояния для каждого экземпляра.

• Serial number - строка, созданная adb для уникальной идентификации экземпляра эмулятора/устройства. Строка создается по его номеру порта консоли. Формат строки следующий: < тип > - < номер_порта_консоли >, например emulator-5554.
• State - состояние соединения экземпляра. Оно может быть одним из 3 вариантов: offline, device, no device.

offline — экземпляр не подключен к adb или не отвечает.
device — экземпляр в настоящее время подключен к серверу adb. Имейте в виду, что это состояние не означает, что система Android полностью загрузилась и работоспособна, поскольку экземпляр подключается к adb тогда, когда система все еще загружается. Однако, после загрузки это нормальное рабочее состояние экземпляра эмулятора/устройства.
no device — нет подключенных эмуляторов/устройств.

Вывод для каждого экземпляра сформатирован так:

serialNumber state 

Пример, показывающий вывод команды devices:

adb devices
List of devices attached
emulator-5554 device
emulator-5556 device
emulator-5558 device

[Направление команд на определенно заданный экземпляр эмулятора/устройства]

Если одновременно работает несколько экземпляров эмуляторов/устройств, то Вы должны прямо указать в команде adb, для какого целевого устройства она предназначена. Чтобы сделать это, используйте опцию -s в командах. Используется опция -s следующим образом:

adb -s < serialNumber > < command > 

Как здесь показано, Вы указываете целевой экземпляр для команды, используя для этого серийный номер, назначенный adb. Серийные номера запущенных эмуляторов/устройств Вы можете узнать, используя команду devices. Вот пример команды, использующей указание целевого устройства:

adb -s emulator-5556 install helloWorld.apk 

Имейте в виду, что если будет выдана команда без указания целевого экземпляра, и при этом имеется несколько доступных эмуляторов/устройств, то adb выдаст ошибку.

Если у Вас несколько доступных устройств (реальных аппаратных или эмулируемых), но только один эмулятор, просто указывайте опцию -e для отправки команд к этому эмулятору. Аналогично, если у Вас есть несколько устройств, но только одно из них реальное, подключенное через USB или Wi-Fi, используйте опцию -d для отправки команд к аппаратному устройству.

[Установка приложений на эмулятор/устройство]

Вы можете использовать adb для копирования приложения из Вашей среды разработки (с хоста отладки) и установить приложение на экземпляр эмулятора/устройства. Чтобы сделать это, используйте команду install. С этой командой Вы должны указать путь до файла .apk (path_to_apk), который Вы хотите установить:

adb install < path_to_apk > 

Для дополнительной информации о том, как создать файл .apk, который можно установить на экземпляр эмулятора/устройства, см. статью "Сборка и запуск" (Building and Running [2]).

Имейте в виду, что если Вы используете Eclipse IDE, и у Вас имеется установленный плагин ADT, то Вам не нужно напрямую использовать adb (или aapt) для установки Вашего приложения на эмулятор/устройство. Все функции по упаковки и инсталляции приложения берет на себя плагин ADT.

[Перенаправление портов]

Вы можете использовать команду forward для настройки произвольного перенаправления порта — перенаправление осуществляется на указанном порте хоста на другой порт экземпляра эмулятора/устройства. Здесь показано, как установить перенаправление порта хоста 6100 на порт эмулятора/устройства 7100:

adb forward tcp:6100 tcp:7100 

Вы также можете использовать adb для настройки перенаправления именованных абстрактных сокетов домена (named abstract UNIX domain sockets), как показано в этом примере:

adb forward tcp:6100 local:logd 

[Обмен файлами с экземпляром эмулятора/устройства]

Вы можете использовать adb-команды pull и push для копирования файлов в на эмулятор/устройство и из него. В отличие от команды install которая копирует только файл APK в специфическое место на эмуляторе/устройстве, команды pull и push commands позволяют Вам копировать любые файлы (и каталоги) в произвольное место.

Для копирования файла или каталога (вместе со всеми его подкаталогами) с эмулятора или устройства на хост отладки, используйте команду:

adb pull < remote > < local > 

Для обратного копирования (с хоста отладки на устройство) используйте команду:

adb push < local > < remote > 

Как Вы уже наверное догадались, remote это путь на экземпляре эмулятора/устройства, local это путь на хосте отладки. Пример:

adb push foo.txt /sdcard/foo.txt 

[Выдача команд Shell]

Для того, чтобы запускать UNIX-команды на отлаживаемом устройстве/эмуляторе совсем не обязательно организовывать подключение к нему через telnet или ssh. Утилита adb предоставляет Вам такую возможность в виде adb shell. В пределах adb shell Вы можете с помощью инструмента activity manager (am) выполнять различные действия в системе, такие как запуск активности (activity), принудительно остановить процесс, опрашивать намерения (broadcast an intent), модифицировать свойства экрана устройства, и многое другое. В пределах shell синтаксис будет следующий:

am < command > 

Вы также можете выдать команду activity manager напрямую из adb без входа в remote shell, например:

adb shell am start -a android.intent.action.VIEW 

Таблица 2. Доступные команды activity manager.

Аргументы для < INTENT >

Интент означает в переводе "намерение". Это специальный термин для операционной системы Android (см. Словарик [6]), так что здесь в тексте он не переводится. Для команд activity manager, которые получают аргумент < INTENT >, Вы можете указать intent со следующими опциями:

-a < ACTION > Указывается действие для intent, такое как "android.intent.action.VIEW". Вы можете декларировать это только один раз.

-d < DATA_URI > Указывается строка данных URI для intent, как например "content://contacts/people/1". Вы можете декларировать это только один раз.

-t < MIME_TYPE > Указывается тип MIME, наподобие "image/png". Вы можете декларировать это только один раз.

-c < CATEGORY > Указывается категория для intent, такая как "android.intent.category.APP_CONTACTS".

-n < COMPONENT > Указывается имя компонента с префиксом из имени пакета, чтобы явно создать intent, такое как "com.example.app/.ExampleActivity".

-f < FLAGS > Добавляет флаги для intent, как поддерживается setFlags().

--esn < EXTRA_KEY > Добавляет null extra. Эта опция не поддерживается для URI intent.

-e|--es < EXTRA_KEY > < EXTRA_STRING_VALUE > Добавляет данные строки как пару ключ-значение.

--ez < EXTRA_KEY > < EXTRA_BOOLEAN_VALUE > Добавляет данные boolean как пару ключ-значение.

--ei < EXTRA_KEY > < EXTRA_INT_VALUE > Добавляет данные integer data как пару ключ-значение.

--el < EXTRA_KEY > < EXTRA_LONG_VALUE > Добавляет данные long как пару ключ-значение.

--ef < EXTRA_KEY > < EXTRA_FLOAT_VALUE > Добавляет данные float как пару ключ-значение.

--eu < EXTRA_KEY > < EXTRA_URI_VALUE > Добавляет данные URI как пару ключ-значение.

--ecn < EXTRA_KEY > < EXTRA_COMPONENT_NAME_VALUE > Добавляет имя компонента, которое преобразовывается и передается объекту ComponentName.

--eia < EXTRA_KEY > < EXTRA_INT_VALUE >[,< EXTRA_INT_VALUE...] Добавляет массив чисел integer.

--ela < EXTRA_KEY > < EXTRA_LONG_VALUE >[,< EXTRA_LONG_VALUE...] Добавляет массив чисел long.

--efa < EXTRA_KEY >[,< EXTRA_FLOAT_VALUE...] Добавляет массив чисел float.

--grant-read-uri-permission Подключает флаг FLAG_GRANT_READ_URI_PERMISSION.

--grant-write-uri-permission Подключает флаг FLAG_GRANT_WRITE_URI_PERMISSION.

--debug-log-resolution Подключает флаг FLAG_DEBUG_LOG_RESOLUTION.

--exclude-stopped-packages Подключает флаг FLAG_EXCLUDE_STOPPED_PACKAGES.

--include-stopped-packages Подключает флаг FLAG_INCLUDE_STOPPED_PACKAGES.

--activity-brought-to-front Подключает флаг FLAG_ACTIVITY_BROUGHT_TO_FRONT.

--activity-clear-top Подключает флаг FLAG_ACTIVITY_CLEAR_TOP.

--activity-clear-when-task-reset Подключает флаг FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET.

--activity-exclude-from-recents Подключает флаг FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS.

--activity-launched-from-history Подключает флаг FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY.

--activity-multiple-task Подключает флаг FLAG_ACTIVITY_MULTIPLE_TASK.

--activity-no-animation Подключает флаг FLAG_ACTIVITY_NO_ANIMATION.

--activity-no-history Подключает флаг FLAG_ACTIVITY_NO_HISTORY.

--activity-no-user-action Подключает флаг FLAG_ACTIVITY_NO_USER_ACTION.

--activity-previous-is-top Подключает флаг FLAG_ACTIVITY_PREVIOUS_IS_TOP.

--activity-reorder-to-front Подключает флаг FLAG_ACTIVITY_REORDER_TO_FRONT.

--activity-reset-task-if-needed Подключает флаг FLAG_ACTIVITY_RESET_TASK_IF_NEEDED.

--activity-single-top Подключает флаг FLAG_ACTIVITY_SINGLE_TOP.

--activity-clear-task Подключает флаг FLAG_ACTIVITY_CLEAR_TASK.

--activity-task-on-home Подключает флаг FLAG_ACTIVITY_TASK_ON_HOME.

--receiver-registered-only Подключает флаг FLAG_RECEIVER_REGISTERED_ONLY.

--receiver-replace-pending Подключает флаг FLAG_RECEIVER_REPLACE_PENDING.

--selector Требует использования опций -d и -t для установки типа и данных intent.

< URI > < COMPONENT > < PACKAGE > Вы можете прямо указать URI, имя пакета и имя компонента, когда это не квалифицируется одной из вышеуказанных опций. Когда аргумент не квалифицирован, утилита подразумевает, что аргумент это URI, если в нем содержится ":" (двоеточие); имя компонента подразумевается, если в нем содержится "/" (прямой слеш); иначе под аргументом подразумевается имя пакета.

[Использование менеджера пакетов (package manager, pm)]

В среде adb shell Вы можете запускать команды менеджера пакетов (pm). Этот инструмент выполняет действия и запросы на пакетах приложений, установленных на устройствах. В командной строке шелла adb синтаксис будет следующий:

pm < command > 

Вы также можете выдать команду для менеджера пакетов с помощью adb напрямую, не заходя в remote shell, например:

adb shell pm uninstall com.example.MyApp 

Таблица 3. Команды, доступные для менеджера пакетов.

[Проверка баз данных sqlite3 из командной строки remote shell]

Из командной строки adb remote shell Вы можете использовать утилиту командной строки sqlite3 для обслуживания баз данных SQLite, созданных для приложений Android. Инструмент sqlite3 включает в себя много полезных команд, таких как .dump для печати содержимого таблицы и .schema для печати оператора SQL CREATE существующей таблицы. Инструмент также дает возможность выполнять команды SQLite на лету.

Чтобы использовать sqlite3, войдите в remote shell на экземпляре эмулятора (или подключенного устройства), как это было описано ранее, и затем запустите утилиту командой sqlite3. Опционально, когда вызываете sqlite3, Вы можете указать полный путь к базе данных, к которой хотите получить доступ. Экземпляры эмулятора/устройства сохраняют базы данных SQLite3 в папке /data/data/< package_name >/databases/.

adb -s emulator-5554 shell
# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db
SQLite version 3.3.12
Enter ".help" for instructions
.... enter commands, then quit...
sqlite> .exit

Как только Вы запустили sqlite3, можете использовать команды sqlite3 в командной строке. Для выхода и возврата в командную оболочку adb remote shell, используйте команду exit или CTRL+D.

[Запись экрана устройства]

Команда screenrecord является утилитой для записи экрана устройств, работающих под управлением Android 4.4 (начиная с API level 19) или в более свежей версии. Утилита записывает activity на экране в файл MPEG-4, который Вы можете загрузить и использовать как часть для видеопрезентации. Эта утилита полезна для разработчиков, кто хочет создать рекламный ролик или обучающие видео без использования отдельного записывающего устройства.

Для использования screenrecord из командной строки, введите следующее:

$ adb shell screenrecord /sdcard/demo.mp4 

Остановить запись экрана можно нажатием Ctrl-C, или запись закончится автоматически через 3 минуты или до истечения времени, установленного опцией --time-limit.

Вот пример сессии записи, использующей adb shell для захвата видео и команду pull для загрузки файла на хост отладки:

$ adb shell
shell@ $ screenrecord --verbose /sdcard/demo.mp4
(press Ctrl-C to stop)
shell@ $ exit
$ adb pull /sdcard/demo.mp4

Утилита screenrecord может записывать в любом поддерживаемом разрешении экрана и с любым битрейтом, который Вы запросите, при сохранении соотношения сторон дисплея устройства. Утилита записывает в собственном разрешении экрана и в ориентации экрана по умолчанию, с максимальной длительностью видео 3 минуты.

Есть некоторые известные ограничения утилиты screenrecord, которые Вы должны учитывать при использовании:

• Некоторые устройства не могут записывать в собственном разрешении экрана. Если Вы столкнетесь с проблемами при записи экрана, попробуйте использовать разрешение поменьше.
• Поворот экрана во время записи не поддерживается. Если при записи произошел поворот экрана, Некоторая часть экрана в записи может отсутствовать.
• Звук в видеофайле не записывается.

Таблица 4. Опции утилиты screenrecord.

screenrecord --bit-rate 6000000 /sdcard/demo.mp4

[UI/Application Exerciser Monkey]

Monkey (переводится как обезьянка) является программой, которая запускается на Вашем эмуляторе или устройстве, и генерирует псевдослучайный поток событий пользователя - такие как клики, касания или жесты, как и некоторое количество событий на уровне системы. Вы можете использовать Monkey для стресс-теста приложений, которые Вы разрабатываете - случайным, но все же воспроизводимым способом.

Самый простой способ использовать обезьянку - запустить следующую команду, которая запустит приложение и будет посылать ему 500 псевдослучайных событий:

adb shell monkey -v -p your.package.name 500 

Для дополнительной информации по командным опциям Monkey см. полное руководство [3].

[Другие команды adb shell]

Чтобы получить список всех допустимых программ для шелла, выполните следующую команду:

adb shell ls /system/bin 

Для большинства команд имеется встроенный help. В таблице перечислены некоторые общие команды adb shell.

Таблица 5. Некоторые другие команды adb shell.

[Разрешение работы лога logcat]

Система логгинга Android предоставляет механизм для сбора и просмотра отладочного вывода системы (system debug output). Логи из разных приложений, а также частично системы собираются в серии кольцевых буферов, которые можно посмотреть (с возможностью фильтрации) командой logcat.

Вы можете использовать команду logcat, чтобы просмотреть и следовать содержимому буферов логов системы. Общий принцип использования следующий:

[adb] logcat [option] ... [filter-spec] ... 

Вы можете использовать команду logcat с хоста отладки или из remote adb shell в экземпляре эмулятора/устройства. Чтобы просмотреть вывод в лог на Вашем хосте отладки, используйте команду:

adb logcat 

Из командной строки remote adb shell используйте команду:

logcat 

Для получения подробной информации по опциям командной строки logcat и по возможностям фильтрации вывода см. документацию [4].

[Остановка сервера adb]

В некоторых случаях Вам может потребоваться возможность прервать работу процесса сервера adb, и затем перезапустить его. Например, adb перестал отвечать на команду, тогда Вы можете прервать работу сервера и запустить его заново, что может устранить проблему.

Чтобы остановить сервер adb, используйте команду kill-server. Вы можете затем запустить сервер заново выдачей любой другой команды adb.

[Ссылки]

1. Android Debug Bridge site:developer.android.com.
2. Building and Running site:developer.android.com.
3. UI/Application Exerciser Monkey site:developer.android.com.
4. Reading and Writing Logs site:developer.android.com.
5. Android Developer Tools site:developer.android.com.
6. Словарик Android.