Difference between revisions of "ADB"

[unchecked revision] [quality revision]
(Implementing ADB)
 

The Android Debug Bridge (ADB) is a versatile command-line tool that lets you communicate with a device (an emulator or a connected Android device).

This article is intended for Developer Package or Distribution Package users (see Which Package better suits your needs for more information).

ADB.png

  • The ADB client is an executable that can be launched with a subcommand such as adb shell or adb logcat.
  • The ADB server acts as a proxy between adb clients and adbd.
  • The ADBD daemon is started by executing an init command on the target device.

The target device can be connected using different solutions:


As soon as it is connected, you can start testing your application with Android Studio.


It is also possible to execute all ADB commands (see ADB commands for more details).

For that purpose, search for the ADB tool in your environment: Host computer installation.

1 Host computer installation[edit]

ADB is available by default within Android Studio IDE (part of the Android SDK) for Linux®, Windows® and OS X®,.


When required, ADB commands can be executed directly within Android Studio Terminal.

Go to the correct directory (<SDK path>/platform-tools)

cd <SDK path>
cd platform-tools

The <SDK path> can be determined by opening the SDK Manager from Android Studio. Select "Tools/Android/SDK Manager" menu:

Android SDK Path

Info white.png Information
If you are using a Distribution Package, please refer to ADB for Distribution Package

2 Commands[edit]

The ADB commands enable the execution of a variety of actions on the target device, such as installing and debugging apps. They also provide access to a Unix shell that can be used to run a variety of commands.

See ADB commands summary for more information.

3 Device connection[edit]

3.1 How to connect over USB[edit]

Follow the steps below to connect your device:

3.1.1 Host computer configuration[edit]

The installation and configuration depend on the host computer OS used:

3.1.1.1 Linux® Host (Ubuntu)[edit]

In Linux environments, the Android USB drivers are built-in. The only action required is to set the target device information.

Info white.png Information
To peform this action, you need administrator rights. In addition, you may need to add sudo in front of each executed command

To do this, open a terminal and

  • Create (or update if it already exists) the 51-android.rules file in /etc/udev/rules.d/ with the following information
    • idVendor = 0483 (STMicroelectronics vendor)
    • idProduct = 0adb (ADB on STMicroelectronics device)
    • Mode = 0666 (read/write permissions)
    • Group = plugdev (Unix group which owns the device node)
Info white.png Information
Check if you belong to the plugdev group by executing the following command:
$ groups

Example:

# ADB on STMicroelectronics devices
SUBSYSTEM=="usb", ATTR{idVendor}=="0483", ATTR{idProduct}=="0adb", MODE="0660", GROUP="plugdev"
  • Make sure that the access rights to the created file are the correct ones:
 chmod a+r /etc/udev/rules.d/51-android.rules

At this stage, your USB driver is correctly installed and configured.

3.1.1.2 Windows Host[edit]

In Windows environments, it is required to install the USB driver and set the target device information.

Warning white.png Warning
Execute all the instructions below before installing the driver.

Follow the instructions provided in the Android Studio website to get the USB driver: Get the Google USB Driver.

Then edit the android_winusb.inf file available in the usb_driver directory and add the following data under each section (for example under [Google.NTx86] and under [Google.NTamd64]):

%SingleAdbInterface%        = USB_Install, USB\VID_0483&PID_0ADB
%CompositeAdbInterface%     = USB_Install, USB\VID_0483&PID_0ADB&MI_00
%SingleAdbInterface%        = USB_Install, USB\VID_0483&PID_0ADB&REV_0409
%CompositeAdbInterface%     = USB_Install, USB\VID_0483&PID_0ADB&REV_0409&MI_00

The driver installation procedure can differ depending on your Windows OS version (see Installing a USB Driver).

At this stage, the USB driver is correctly installed and configured.

3.1.1.3 OS X Host[edit]

In OS X environments, the Android USB drivers are built-in and no manual configuration is required to install and configure the USB driver.

3.1.2 Target device configuration[edit]

Prerequisite: Use ST Android distribution to start the target device and access the Android user interface.


On the target device:

  • Disconnect the USB cable between the target device and the host computer (if it is connected).
  • Find the Settings > Developer options configuration screen on your target device (if it is not visible, select Settings > About device and click the Build number menu entry seven times).
  • Enable the USB Debugging option from the Settings > Developer options menu.
  • Reconnect the USB cable between the target device and the host computer.
  • If an alert is displayed on your target device requesting permission to "Allow USB debugging," click OK. It is recommended to check the "Always allow from this computer" option to avoid this from happening each time the target device is connected to the same host computer.

3.1.3 Checking the device connection[edit]

First, ensure that the device is connected on the host computer through a USB cable, and that it has been started.

Android Studio embeds a tool named Device Monitor (available from Android studio: "Tools/Android/Android Device Monitor" menu). Launch it and check that the target device is available in the (name of the device starting by stmicroelectronics) list.

Android Device Monitor


3.2 How to connect over Ethernet[edit]

To use ADB over an Ethernet connection, connect the host computer and the target device on the same network.

First, follow the instructions provided in How to connect over USB.

Then:

  • Connect the USB cable between the target device and the host computer.
  • Open a terminal on your host computer.
    • Go to the <SDK path>/platform-tools/ directory (see Host computer installation to know how to get the <SDK path>).
    • Execute adb shell ifconfig to get the target IP address <device_ip_address>.
    • Execute adb tcpip 5555 to set the TCP/IP connection over port 5555.
  • Disconnect the USB cable between the target device and the host computer.
  • Execute adb connect <device_ip_address> to reconnect on the device through Ethernet

3.3 How to connect over Wi-Fi[edit]

Follow the instructions provided in the Android Studio website: Connect to a device over Wi-Fi

4 ADB for Distribution Package[edit]

4.1 Installing the Host computer[edit]

By default, ADB is built when you compile the ST Android distribution. It is automatically added to your environment's $PATH.

Another possibility is to install ADB but executing apt-get install android-tools-adb, although this may be a hindrance to the development in case of ST Android distribution and OS adb version mismatch (the server is restarted every time it is used with a mismatched version of an adb client).


The device is not necessarily visible in the terminal when executing adb devices. If this is not the case:

  • Create a file within ~/.android/ directory named adb_usb.ini.
  • Add one line containing STMicrolectronics idVendor:
0x0483

4.2 Implementing ADB[edit]

ADB source code is stored in system/core/adb (common files between host and target device are differentiated by the ADB_HOST tag).


Three properties can be configured for ADB (set within the device/stm/<BoardId>/device.mk):

  • persist.adb.trace_mask → used to enable or disable ADBD traces on target device.
- Possible values (listed in system/core/adb/adb_trace.cpp): 0, 1 (or all), adb, sockets, packets, rwx, usb, sync, sysdeps, transport, jdwp, services, auth, fdevent or shell
- As soon as the persist.adb.trace_mask property is updated, need to stop and start adbd service
 stop adbd
 setptop persist.adb.trace_mask = <value>
 start adbd
-
Info white.png Information

Traces are available in /data/adb/adb-

<date>

<date_at_start>

  • ro.adb.secure → used to enable or disable the authentication mechanism (1: authentication enabled, 0: authentication disabled). This property can not be modified dynamically. It is considered only in case of eng or userdebug image builds. It is ignored otherwise (the authentication mechanism is enabled by default for user build).
  • service.adb.tcp.port → used to enable the TCP/IP port if a wireless connection is used (this property is not set by default as it is not necessary for USB).


ADB is an Android specific gadget device available in user space. functionfs must be mounted since it is used to create this gadget device and register it to the USB Device Controller (UDC). Three endpoints are used (one for control, one for data input, one for data output).


It is also possible to create a composite device between ADB and other protocols, using the configfs mechanism.

Open the device/stm/<STM32Series>/<BoardId>/init.stm.usb.rc file to understand how the USB is configured for ADB, and the file system/core/rootdir/init.usb.configfs.rc for information on the USB composite devices available (by default).


ADB over USB is the default configuration within the Android baseline. By default, it is configured as follows:

  • persist.adb.trace_mask: [0] → no ADB trace
  • ro.adb.secure: [1] → authentication mechanism enabled (connection must be acknowledged through a popup on the target device)
  • persist.sys.usb.config: [adb] → USB ADB gadget device
  • sys.usb.config: [adb] → USB ADB gadget device
  • sys.usb.state: [adb] → USB ADB gadget device

The ADB over wireless connection can be set within your distribution (Ethernet or Wi-Fi) by adding the following property in /device/stm/<STM32Series>/<BoardId>/device.mk:

PRODUCT_PROPERTY_OVERRIDES += service.adb.tcp.port=5555


The Android Debug Bridge (ADB) is a versatile command-line tool that lets you communicate with a device (an emulator or a connected Android device).

This article is intended for Developer Package or Distribution Package users (see [[Which STM32MPU Embedded Software Package for Android better suits your needs|Which Package better suits your needs]] for more information).

[[File:ADB.png|400px]]
* The '''ADB client''' is an executable that can be launched with a subcommand such as <code>adb shell</code> or <code>adb logcat</code>.
*  The '''ADB server''' acts as a proxy between adb clients and adbd.
*  The '''ADBD daemon''' is started by executing an init command on the target device.

The target device can be connected using different solutions:
* [[#How_to_connect_over_USB | How to connect over USB]] (default)
* [[#How_to_connect_over_Ethernet | How to connect over Ethernet]]
* [[#How_to_connect_over_Wi-Fi | How to connect over Wi-Fi]]

As soon as it is connected, you can start testing your application with ''Android Studio''.

It is also possible to execute all ADB commands (see [[#Commands | ADB commands]] for more details).

For that purpose, search for the ADB tool in your environment: [[#Host_computer_installation | Host computer installation]].

== Host computer installation ==
ADB is available by default within ''Android Studio'' IDE (part of the Android SDK) for Linux<sup>&reg;</sup>, Windows<sup>&reg;</sup> and OS X<sup>&reg;</sup>,. 

When required, ADB commands can be executed directly within ''Android Studio'' Terminal.

Go to the correct directory (''<SDK path>/platform-tools'')
 cd {{HighlightParam|''<SDK path>''}}
 cd platform-tools

The {{HighlightParam|''<SDK path>''}} can be determined by opening the SDK Manager from Android Studio. Select "Tools/Android/SDK Manager" menu:

[[Image:Android_SDK.png|800px|link=|Android SDK Path]]

{{Info| If you are using a Distribution Package, please refer to  [[#ADB for Distribution Package | ADB for Distribution Package]]}}

== Commands ==
The ADB commands enable the execution of a variety of actions on the target device, such as installing and debugging apps. They also provide access to a Unix shell that can be used to run a variety of commands.

See [http://developer.android.com/tools/help/adb.html#commandsummary ADB commands summary] for more information.

== Device connection ==

=== How to connect over USB ===
Follow the steps below to connect your device:
* [[#Host_computer_configuration | Configure your host computer]]
* [[#Target_device_configuration | Configure your target device]]
* [[#Checking_the_device_connection | Check the device connection]]

==== Host computer configuration ====

The installation and configuration depend on the host computer OS used:
* [[#Linux.C2.AE_Host_.28Ubuntu.29 | Linux Host (Ubuntu) case]] 
* [[#Windows_Host | Windows Host case]]
* [[#OS_X_Host | OS X Host case]]

===== Linux<sup>&reg;</sup> Host (Ubuntu) =====

In Linux environments, the Android USB drivers are built-in. The only action required is to set the target device information.
{{Info|To peform this action, you need administrator rights. In addition, you may need to add ''sudo'' in front of each executed command}}

To do this, open a terminal and 
* Create (or update if it already exists) the ''51-android.rules'' file in ''/etc/udev/rules.d/'' with the following information
** ''idVendor'' = 0483 (STMicroelectronics vendor)
** ''idProduct'' = 0adb (ADB on STMicroelectronics device)
** ''Mode'' = 0666 (read/write permissions)
** ''Group'' = plugdev (Unix group which owns the device node)

{{Info|Check if you belong to the ''plugdev'' group by executing the following command: <pre>$ groups</pre>}}

Example:
 # ADB on STMicroelectronics devices
 SUBSYSTEM=="usb", ATTR{idVendor}=="0483", ATTR{idProduct}=="0adb", MODE="0660", GROUP="plugdev"

* Make sure that the access rights to the created file are the correct ones:
  chmod a+r /etc/udev/rules.d/51-android.rules

At this stage, your USB driver is correctly installed and configured.

===== Windows Host =====

In Windows environments, it is required to install the USB driver and set the target device information.

{{Warning|Execute all the instructions below before installing the driver.}}

Follow the instructions provided in the ''Android Studio'' website to get the USB driver: [https://developer.android.com/studio/run/win-usb.html Get the Google USB Driver].

Then edit the ''android_winusb.inf'' file available in the ''usb_driver'' directory and add the following data under each section (for example under [Google.NTx86] and under [Google.NTamd64]):
 %SingleAdbInterface%        = USB_Install, USB\VID_0483&PID_0ADB
 %CompositeAdbInterface%     = USB_Install, USB\VID_0483&PID_0ADB&MI_00
 %SingleAdbInterface%        = USB_Install, USB\VID_0483&PID_0ADB&REV_0409
 %CompositeAdbInterface%     = USB_Install, USB\VID_0483&PID_0ADB&REV_0409&MI_00

The driver installation procedure can differ depending on your Windows OS version (see [https://developer.android.com/studio/run/oem-usb.html#InstallingDriver Installing a USB Driver]).

At this stage, the USB driver is correctly installed and configured.

===== OS X Host =====

In OS X environments, the Android USB drivers are built-in and no manual configuration is required to install and configure the USB driver.

==== Target device configuration ====
<u>Prerequisite</u>: Use ST Android distribution to start the target device and access the Android user interface.

On the target device:
* Disconnect the USB cable between the target device and the host computer (if it is connected).
* Find the ''Settings > Developer options'' configuration screen on your target device (if it is not visible, select ''Settings > About device'' and click the ''Build number'' menu entry seven times).
* Enable the USB Debugging option from the ''Settings > Developer options'' menu.
* Reconnect the USB cable between the target device and the host computer.
* If an alert is displayed on your target device requesting permission to "Allow USB debugging," click ''OK. It is recommended to check the "Always allow from this computer" option to avoid this from happening each time the target device is connected to the same host computer.

==== Checking the device connection ====

First, ensure that the device is connected on the host computer through a USB cable, and that it has been started.

''Android Studio'' embeds a tool named ''Device Monitor''  (available from Android studio: "Tools/Android/Android Device Monitor" menu). Launch it and check that  the target device is available in the (name of the device starting by ''stmicroelectronics'') list.

[[Image:AndroidDeviceMonitor.png|800px|link=|Android Device Monitor]]

{{ReviewsComments| JPR 06Sept'19: with windows, to use adb with the console, need also to add the Android SDK platform-tools path in the ''path'' environment variable if not already done}}

=== How to connect over Ethernet ===

To use ADB over an Ethernet connection, connect the host computer and the target device on the same network.

First, follow the instructions provided in [[#How_to_connect_over_USB | How to connect over USB]].

Then:
* Connect the USB cable between the target device and the host computer.
* Open a terminal on your host computer.
** Go to the ''{{HighlightParam|<SDK path>}}/platform-tools/'' directory (see [[#Host_computer_installation | Host computer installation]] to know how to get the {{HighlightParam|<SDK path>}}).
** Execute ''adb shell ifconfig'' to get the target IP address <device_ip_address>.
** Execute ''adb tcpip 5555'' to set the TCP/IP connection over port 5555.
* Disconnect the USB cable between the target device and the host computer.
* Execute ''adb connect {{HighlightParam|<device_ip_address>}}'' to reconnect on the device through Ethernet

=== How to connect over Wi-Fi ===

Follow the instructions provided in the ''Android Studio'' website: [https://developer.android.com/studio/command-line/adb.html#wireless Connect to a device over Wi-Fi]

== ADB for Distribution Package==

=== Installing the Host computer ===

By default, ''ADB'' is built when you compile the ST Android distribution. It is automatically added to your environment's $PATH.

Another possibility is to install ADB but executing ''apt-get install android-tools-adb'', although this may be a hindrance to the development in case of ST Android distribution and OS adb version mismatch (the server is restarted every time it is used with a mismatched version of an adb client).

The device is not necessarily visible in the terminal when executing ''adb devices''. If this is not the case:
* Create a file within ~/.android/ directory named adb_usb.ini.
* Add one line containing STMicrolectronics idVendor:
 0x0483

=== Implementing ADB ===
ADB source code is stored in ''system/core/adb'' (common files between host and target device are differentiated by the ADB_HOST tag).

Three properties can be configured for ADB (set within the ''device/stm/<BoardId>/device.mk''):
* ''persist.adb.trace_mask'' → used to enable or disable ADBD traces on target device.
::- Possible values (''listed in <code>system/core/adb/adb_trace.cpp</code>''): 0, 1 (or all), adb, sockets, packets, rwx, usb, sync, sysdeps, transport, jdwp, services, auth, fdevent or shell::- As soon as the ''persist.adb.trace_mask'' property is updated, need to stop and start adbd service {{Board$}} stop adbd
 {{Board$}} setptop persist.adb.trace_mask = {{HighlightParam|''<value>''}}
 {{Board$}} start adbd::-{{Info|

Traces are available in <code>/data/adb/adb-{{HighlightParam|''<date>''}}<date_at_start>''}}</code>

}}* ''ro.adb.secure'' → used to enable or disable the authentication mechanism (1: authentication enabled, 0: authentication disabled). This property can not be modified dynamically. It is considered only in case of ''eng'' or ''userdebug'' image builds. It is ignored otherwise (the authentication mechanism is enabled by default for user build). 
* ''service.adb.tcp.port'' → used to enable the TCP/IP port if a wireless connection is used (this property is not set by default as it is not necessary for USB).

ADB is an Android specific gadget device available in user space. functionfs must be mounted since it is used to create this gadget device and register it to the USB Device Controller (UDC). Three endpoints are used (one for control, one for data input, one for data output).

It is also possible to create a composite device between ADB and other protocols, using the configfs mechanism.

Open the ''device/stm/{{HighlightParam|<STM32Series>}}/{{HighlightParam|<BoardId>}}/init.stm.usb.rc'' file to understand how the USB is configured for ADB, and the file ''system/core/rootdir/init.usb.configfs.rc'' for information on the USB composite devices available (by default).

ADB over USB is the default configuration within the Android baseline. By default, it is configured as follows:
* ''persist.adb.trace_mask'': [0] → no ADB trace 
* ''ro.adb.secure'': [1] → authentication mechanism enabled (connection must be acknowledged through a popup on the target device)
* ''persist.sys.usb.config'': [adb] → USB ADB gadget device
* ''sys.usb.config'': [adb] → USB ADB gadget device
* ''sys.usb.state'': [adb] → USB ADB gadget device

The ADB over wireless connection can be set within your distribution (Ethernet or Wi-Fi) by adding the following property in ''/device/stm/{{HighlightParam|<STM32Series>}}/{{HighlightParam|<BoardId>}}/device.mk'':
 PRODUCT_PROPERTY_OVERRIDES += service.adb.tcp.port=5555
<noinclude>

[[Category:Android debugging tools]]
[[Category:Android]]
{{PublicationRequestId | 13250 | 2019-09-12}}</noinclude>
Line 164: Line 164:
 
Three properties can be configured for ADB (set within the ''device/stm/<BoardId>/device.mk''):
 
Three properties can be configured for ADB (set within the ''device/stm/<BoardId>/device.mk''):
 
* ''persist.adb.trace_mask'' → used to enable or disable ADBD traces on target device.
 
* ''persist.adb.trace_mask'' → used to enable or disable ADBD traces on target device.
::- Possible values (''listed in <code>system/core/adb/adb_trace.cpp</code>''): 0, 1 (or all), adb, sockets, packets, rwx, usb, sync, sysdeps, transport, jdwp, services, auth, fdevent or shell
+
::Possible values (''listed in <code>system/core/adb/adb_trace.cpp</code>''): 0, 1 (or all), adb, sockets, packets, rwx, usb, sync, sysdeps, transport, jdwp, services, auth, fdevent or shell
::- As soon as the ''persist.adb.trace_mask'' property is updated, need to stop and start adbd service
 
 
  {{Board$}} stop adbd
 
  {{Board$}} stop adbd
 
  {{Board$}} setptop persist.adb.trace_mask = {{HighlightParam|''<value>''}}
 
  {{Board$}} setptop persist.adb.trace_mask = {{HighlightParam|''<value>''}}
 
  {{Board$}} start adbd
 
  {{Board$}} start adbd
::- Traces are available in /data/adb/adb-{{HighlightParam|''<date>''}}
+
{{Info|
  +
Traces are available in <code>/data/adb/adb-{{HighlightParam|''<date_at_start>''}}</code>
  +
}}
 
* ''ro.adb.secure'' → used to enable or disable the authentication mechanism (1: authentication enabled, 0: authentication disabled). This property can not be modified dynamically. It is considered only in case of ''eng'' or ''userdebug'' image builds. It is ignored otherwise (the authentication mechanism is enabled by default for user build).  
 
* ''ro.adb.secure'' → used to enable or disable the authentication mechanism (1: authentication enabled, 0: authentication disabled). This property can not be modified dynamically. It is considered only in case of ''eng'' or ''userdebug'' image builds. It is ignored otherwise (the authentication mechanism is enabled by default for user build).  
 
* ''service.adb.tcp.port'' → used to enable the TCP/IP port if a wireless connection is used (this property is not set by default as it is not necessary for USB).
 
* ''service.adb.tcp.port'' → used to enable the TCP/IP port if a wireless connection is used (this property is not set by default as it is not necessary for USB).