# Android Debug Bridge

Android Debug Bridge (ADB) is a versatile toolset present on most Android devices that facilitates a variety of device actions, such as installing and debugging apps. Automate can use its features in multiple ways:

- Automate includes a privileged service that can be started using ADB, which then run in the background to let blocks access system feature that’s otherwise inaccessible to regular apps.
- The ADB shell command block that can connect through ADB to an Android device, including the device running the app, to execute shell commands with elevated capabilities beyond regular users/apps.
- Grant the app development permissions with access to some system features that’s otherwise inaccessible to regular apps.

## Setup

A device has to be configured before it allows ADB access. On Android 11+, simply enable the Wireless debugging option in system Developer settings, then Pair device with pairing code to authorize a connection, e.g. from a PC or Automate. On Android 10 or lower a USB connected PC is required:

1. Install the Android Studio to get the `adb` command-line tool.
2. Enable the USB debugging option in system Developer settings.
3. Connect the PC and Android device using a USB cable.
4. On the Android device, allow/authorize the USB connection.
5. On the PC, execute the shell command `adb tcpip 5555`. This step has to be repeated after every device reboot.
6. Disconnect the USB cable.

Warning! When a new ADB host connects or tries to pair, e.g. a PC or Automate, the user has to authorize. Never allow access when an unknown device tries to connect.

## Privileged service

Choose Android Debug Bridge (ADB) as Privileged service start method in settings. On Android 5+, then follow the on screen instructions to pair/authorize Automate with ADB on the device. On Android 4.4 and lower, then follow the setup instructions.

If an EACCES `SocketException` failure occurs, try disabling the system “Data Saver” feature, for just Automate or globally.

Once paired/authorized the service will start automatically when it’s first used, e.g. by a block using it, then run in the background until the system kills it, the device is rebooted, or the app is uninstalled or updated. On Android 10+ when using Wireless debugging the service will search for the port that ADB uses by its DNS Service Discovery (DNS-SD) announcement on the connected Wi-Fi network.

The privileged service can also be started Manually by a connected PC using the `adb` command-line tool by executing:
`adb shell sh /sdcard​/Android​/data​/com.llamalab.automate​/cache​/start.sh`

The privileged service uses a internal key-pair for authentication, it’s inaccessible to flows and not present on the public “key chain” in system Security settings. To revoke it, click the Forget privileged service ADB keys option in settings and/or the Revoke USB debugging authorizations in system Developer settings, or on Android 11+, the Wireless debugging screen in system Developer settings.

To make the service less unreliable:

- Keep the USB debugging enabled in system Developer settings, even on Android 11+ when using Wireless debugging.
- On Android 11+ instead of using Wireless debugging, click the Restart ADB in TCP mode option in settings to use a static port (5555), i.e. same as executing `adb tcpip 5555` on a USB connected PC.
- On Android 11+ turn off the Disable adb authorization timeout in system Developer settings.
- Set the Default/Select USB configuration to No data transfer or Charge only in system Developer settings.
- On Android 7+ disable the system “Data Saver” feature for Automate or globally.

## Development permissions

Either configure the privileged service to use Android Debug Bridge (ADB) then grant the permission in Privileges settings as any other, or execute its respective shell command on a connected PC:

- change system display settings:
  `adb shell pm grant com​.llamalab​.automate android​.permission​.CHANGE_CONFIGURATION`
- intercept volume key long press:
  `adb shell pm grant com​.llamalab​.automate android​.permission​.SET_VOLUME_KEY_LONG_PRESS_LISTENER`
- interact across users:
  `adb shell pm grant com​.llamalab​.automate android​.permission​.INTERACT_ACROSS_USERS`
- limit number of running processes:
  `adb shell pm grant com​.llamalab​.automate android​.permission​.SET_PROCESS_LIMIT`
- modify quiet mode:
  `adb shell pm grant com​.llamalab​.automate android​.permission​.MODIFY_QUIET_MODE`
- modify secure system settings:
  `adb shell pm grant com​.llamalab​.automate android​.permission​.WRITE_SECURE_SETTINGS`
- read sensitive log data:
  `adb shell pm grant com​.llamalab​.automate android​.permission​.READ_LOGS`
- retrieve state dump information from system services:
  `adb shell pm grant com​.llamalab​.automate android​.permission​.DUMP`

Before the above commands take effect Automate may have to be restarted:

- System Settings → Apps → Automate → Force close

### Xiaomi

Some manufacturers require additional steps before development permissions can be granted:

- System Settings → Security settings → USB debugging → choose Allow granting permissions

## Install “old” apps on Android 14

Android 14 restricts installation of app APKs that "target" Android 5 or lower, e.g. like the Automate legacy extension, but an official workaround is provided to bypass this restriction using ADB. Download the APK to your PC then execute:
`adb install --bypass-low-target-sdk-block FILENAME.apk`