Manual Version

Disclaimer

While every effort has been made to ensure accuracy in this document, errors or omissions may still exist. Users should carefully assess its applicability; we reserve the right to make revisions at any time and do not guarantee the validity of content from previous versions. For the latest product information, please regularly visit the official website of LCSC Dev Boards for updated materials. The copyright and final interpretation of this document belong to Shenzhen JLC Technology Group Co.,Ltd. Please take note of this disclaimer and assess the risks independently when making decisions. We are not responsible for any issues arising from the use of this document. Thank you for your understanding and support.

Introduction

ADB is a very frequently used tool. This document mainly helps everyone quickly master the installation and usage of ADB, and conduct debugging experiments on the LCSC Taishan-RK3566-Linux Dev Board.

Preparation

• You will need a Windows 10 computer. Other operating systems may work theoretically, but I haven't tested them. For the purposes of this guide, I'll use my computer as an example, and unless otherwise specified, all environment setup and development compilation will assume this configuration.

• The LCSC Taishan-RK3566-Linux Dev Board requires flashing the corresponding Android system firmware.
• ADB firmware package.

Introduction to ADB

ADB, short for Android Debug Bridge, is a command-line tool developed by Google for communication and debugging with Android devices. As part of the Android Software Development Kit (SDK), ADB provides a range of functions and commands that facilitate interactions and debugging operations with Android devices.

The main features and uses of ADB are as follows:

• Device Connection and Management: ADB allows developers to connect Android devices via USB or network and manage them. It can list connected devices, install or uninstall applications, copy files to devices, and more.
• Application Debugging: ADB allows developers to debug applications on connected Android devices. It can start and stop applications, view application logs, monitor CPU and memory usage, and more.
• File Transfer: ADB enables file transfer between a computer and an Android device through the command line. This is useful for installing applications, transferring media files, or backing up data.
• Shell Access: ADB provides an interface to execute shell commands on the device, making it easier for developers to debug devices, log data, query system status, and more.
• Screenshot and Screen Recording: ADB can capture screenshots and record the screen, allowing developers to capture images and animations on the device’s screen for analysis and debugging.
• Port Forwarding: ADB supports forwarding ports from the device to the computer, making it easier for developers to communicate and debug services running on the device through the computer.
• Device Control: ADB offers commands for basic device operations such as rebooting, shutting down, or entering recovery mode.

It is important to note that although ADB was developed for Android, it is widely used on other platforms due to its usefulness and popularity. We can also find it in platforms like Buildroot, Debian, Ubuntu, and others, which we will use later on.

Installation

ADB Download

📌 Download Center (Click to See)

📌 In Download Center->Baidu Netdisk Resource Content->Chapter 07. Development Tools->platform-tools_r33.0.3-windows.zip.

This is for Windows environment.

Download the installation package and extract it. I will directly download and extract it to the D: drive here. You can choose your own location, but when adding environment variables later, you’ll need to specify the corresponding path.

At this point, you can directly use ADB by opening the command line window in the current directory. To do this, enter "cmd" in the file directory bar and press Enter.

Running the adb.exe help command in the command line window will show version information, indicating that ADB is working correctly.

Above, we successfully ran the adb.exe in the same directory. However, in actual use, we want to be able to open CMD from any location and use ADB, so we need to add ADB to the Windows environment variables. Here, we will take Windows 10 as an example, though other versions are similar.

Right-click on the Windows 10 icon and select "System."

Click "Advanced System Settings."

Click "Environment Variables."

Select "Path" in the System variables section, then click "Edit."

Click "New" and then enter the path where adb.exe was downloaded.

Click "OK" to save. Then, open a new CMD window—make sure it is a new one, as previously opened ones will not sync the updated environment variables.

Running adb help and seeing the following log means you have successfully installed it!

Usage

Connecting the LCSC Taishan-RK3566-Linux Dev Board

Many of the following commands require interaction with the LCSC Taishan-RK3566-Linux Dev Board, so we need to connect the board using a Type-C data cable.

• Connect the Type-C cable to the computer. Note: If there is insufficient power, you may need to use a power adapter to supplement the board's power. Ensure the Type-C cable supports data transfer and is not just a charging cable.

• Enable USB debugging on the Android system. The firmware we provide has this enabled by default. If you need to enable it manually, follow these steps:

Enter the Android system-->Settings-->About tablet-->Tap Build number several times to enable Developer mode-->Go back and enter System-->Advanced-->Enable USB debugging

In the Device Manager, you should be able to correctly find the Android ADB Interfaces device.

Learning ADB Commands

The best way to learn is by reading the original documentation. I will highlight some of the most frequently used ADB commands for analysis, but please refer to the official Google manual for more details.

How to Quickly Master ADB Usage

When using command-line tools like ADB, makefile, git, python, Docker, etc., they usually provide a help command that helps you quickly understand how to use them and their available parameters. This information is particularly helpful for beginners, serving as an introductory guide and quick reference. It’s recommended for newcomers to develop the habit of using the help command first when unsure about a tool. Below is the help information; I’ll highlight some important parameters as examples.

C:\Users\win>adb help
Android Debug Bridge version 1.0.41
Version 34.0.1-9680074
Installed as D:\platform-tools\adb.exe
global options:
 -a                       listen on all network interfaces, not just localhost
 -d                       use USB device (error if multiple devices connected)
 -e                       use TCP/IP device (error if multiple TCP/IP devices available)
 -s SERIAL                use device with given serial (overrides $ANDROID_SERIAL)
 -t ID                    use device with given transport id
 -H                       name of adb server host []
 -P                       port of adb server []
 -L SOCKET                listen on given socket for adb server []
 --one-device SERIAL|USB  only allowed with 'start-server' or 'server nodaemon', server will only connect to one USB device, specified by a serial number or USB device address.
 --exit-on-write-error    exit if stdout is closed
general commands:
 devices []             list connected devices (-l for long output)help                     show this help message
 version                  show version num
networking:
 connect HOST[]      connect to a device via TCP/IP []
 disconnect []]
     disconnect from given TCP/IP device [], or all
 pair HOST[] []
     pair with a device for secure TCP/IP communication
 forward --list           list all forward socket connections
 forward [] LOCAL REMOTE
     forward socket connection using:
       tcp:<port> (<localmay be "tcp:0" to pick any open port)
       localabstract:<unix domain socket name>
       localreserved:<unix domain socket name>
       localfilesystem:<unix domain socket name>
       dev:<character device name>
       jdwp:<process pid> (remote only)
       vsock:<CID>:<port> (remote only)
       acceptfd:<fd> (listen only)
 forward --remove LOCAL   remove specific forward socket connection
 forward --remove-all     remove all forward socket connections
 reverse --list           list all reverse socket connections from device
 reverse [] REMOTE LOCAL
     reverse socket connection using:
       tcp:<port> (<remote> may be "tcp:0" to pick any open port)
       localabstract:<unix domain socket name>
       localreserved:<unix domain socket name>
       localfilesystem:<unix domain socket name>
 reverse --remove REMOTE  remove specific reverse socket connection
 reverse --remove-all     remove all reverse socket connections from device
 mdns check               check if mdns discovery is available
 mdns services            list all discovered services
file transfer:
 push [] [] [] LOCAL... REMOTE
     copy local files/directories to device
     --sync: only push files that are newer on the host than the device
     -n: dry run: push files to device without storing to the filesystem
     -z: enable compression with a specified algorithm (any/none/brotli/lz4/zstd)
     -Z: disable compression
 pull [] [] [] REMOTE... LOCAL
     copy files/dirs from device
     -a: preserve file timestamp and mode
     -z: enable compression with a specified algorithm (any/none/brotli/lz4/zstd)
     -Z: disable compressionsync [] [] [] []sync a local build from $ANDROID_PRODUCT_OUT to the device (default all)
     -n: dry run: push files to device without storing to the filesystem
     -l: list files that would be copied, but don't copy them
     -z: enable compression with a specified algorithm (any/none/brotli/lz4/zstd)
     -Z: disable compression
shell:
 shell [] [] [] [] []
     run remote shell command (interactive shell if no command given)
     -e: choose escape character, or "none"; default '~'
     -n: don't read from stdin
     -T: disable pty allocation
     -t: allocate a pty if on a tty (-tt: force pty allocation)
     -x: disable remote exit codes and stdout/stderr separation
 emu COMMAND              run emulator console command
app installation (see also `adb shell cmd package help`):
 install [] [] PACKAGE
     push a single package to the device and install it
 install-multiple [] [] PACKAGE...
     push multiple APKs to the device for a single package and install them
 install-multi-package [] [] PACKAGE...
     push one or more packages to the device and install them atomically
     -r: replace existing application
     -t: allow test packages
     -d: allow version code downgrade (debuggable packages only)
     -p: partial application install (install-multiple only)
     -g: grant all runtime permissions
     --abi ABI: override platform's default ABI
     --instant: cause the app to be installed as an ephemeral install app
     --no-streaming: always push APK to device and invoke Package Manager as separate steps
     --streaming: force streaming APK directly into Package Manager
     --fastdeploy: use fast deploy
     --no-fastdeploy: prevent use of fast deploy
     --force-agent: force update of deployment agent when using fast deploy
     --date-check-agent: update deployment agent when local version is newer and using fast deploy
     --version-check-agent: update deployment agent when local version has different version code and using fast deploy
     (See also
adb shell pm help
 for more options.)
 uninstall [] PACKAGE
     remove this app package from the device
     '-k': keep the data and cache directories
debugging:
 bugreport []
     write bugreport to given PATH [];
     if PATH is a directory, the bug report is saved in that directory.
     devices that don't support zipped bug reports output to stdout.
 jdwp                     list pids of processes hosting a JDWP transport
 logcat                   show device log (logcat --help for more)
security:
 disable-verity           disable dm-verity checking on userdebug builds
 enable-verity            re-enable dm-verity checking on userdebug builds
 keygen FILE
     generate adb public/private key; private key stored in FILE,
scripting:
 wait-for[]-STATE...wait for device to be in a given state
     STATE: device, recovery, rescue, sideload, bootloader, or disconnect
     TRANSPORT: usb, local, or any []
 get-state                print offline | bootloader | device
 get-serialno             print <serial-number>
 get-devpath              print <device-path>
 remount []
      remount partitions read-write. if a reboot is required, -R will
      will automatically reboot the device.
 reboot []
     reboot the device; defaults to booting system image but
     supports bootloader and recovery too. sideload reboots
     into recovery and automatically starts sideload mode,
     sideload-auto-reboot is the same but reboots after sideloading.
 sideload OTAPACKAGE      sideload the given full OTA package
 root                     restart adbd with root permissions
 unroot                   restart adbd without root permissions
 usb                      restart adbd listening on USB
 tcpip PORT               restart adbd listening on TCP on PORT
internal debugging:
 start-server             ensure that there is a server running
 kill-server              kill the server if it is running
 reconnect                kick connection from host side to force reconnect
 reconnect device         kick connection from device side to force reconnect
 reconnect offline        reset offline/unauthorized devices to force reconnect
usb:
 attach                   attach a detached USB device
 detach                   detach from a USB device to allow use by other processes
environment variables:$ADB_TRACE
     comma-separated list of debug info to log:
     all,adb,sockets,packets,rwx,usb,sync,sysdeps,transport,jdwp$ADB_VENDOR_KEYS         colon-separated list of keys (files or directories)$ANDROID_SERIAL          serial number to connect to (see -s)$ANDROID_LOG_TAGS        tags to be used by logcat (see logcat --help)$ADB_LOCAL_TRANSPORT_MAX_PORT max emulator scan port (default 5585, 16 emus)$ADB_MDNS_AUTO_CONNECT   comma-separated list of mdns services to allow auto-connect (default adb-tls-connect)
Online documentation: https://android.googlesource.com/platform/packages/modules/adb/+/refs/heads/master/docs/user/adb.1.md

List Connected Devices

adb devices

This command lists all connected devices. It is rarely used unless multiple development boards are connected at once. For example, here I have connected two Taishan-RK3566 development boards.

Example: Open the command prompt and run the following command

C:\Users\win>adb devices
List of devices attached
4d70015485fe537b        device
4d70015485fe537b        device

This simply shows you that such a feature exists. All subsequent operations will be based on a single device.

Start Device Command Line

• Enter the command

adb shell

• Command Explanation: Connects to the device's shell, allowing you to enter commands directly in the command line, and the device will execute them. For instance, you can run common Linux commands, execute device-specific commands, or use the various features provided by ADB tools.

# Enter the device
adb shell
# Use root privileges
su
# Use ls command in Taishan
ls
# Use pwd to check the path in Taishan
pwd
# Check the kernel logs in Taishan --- very important ---
dmesg
# Check the system-level logs --- very important ---
logcat

• Demonstration example:

- Exit the shell

exit

Install Applications

adb install

Open the command prompt and run the following installation command. Replace C:\Users\win\Downloads\chrome.apk with your actual APK file's location.

C:\Users\win>adb install C:\Users\win\Downloads\chrome.apk
Performing Streamed Install
Success

It will show that the installation was successful, and you'll be able to see the Chrome icon on the Android system.

You can also check if the installation was successful by running the following command. The "adb shell pm list packages" command lists all installed packages, and the grep command filters out the package containing the keyword "chrome." If you want to see all packages, you can omit "| grep chrome".

C:\Users\win>adb shell pm list packages | grep chrome
package:com.android.chrome

Uninstall Applications

To uninstall an app, use the following command:

adb uninstall

First, use the command to list all packages and find the app you want to uninstall:

C:\Users\win>adb shell pm list packages
package:com.android.cts.priv.ctsshim
package:com.android.keychain
package:com.android.chrome
以下省略N行

If you want to uninstall Chrome (as shown in the 4th line above), use:

C:\Users\win>adb uninstall com.android.chrome
Success

Copy Files from Your Computer to the Device

This function is very useful when debugging devices and frequently needing to transfer files. Once you master this command, there's no need for a USB drive anymore.

adb push

Before using the "adb push" command to push files to an Android device, sometimes you need to execute a remount operation to mount the device's file system in a writable mode. By default, the Android device's file system is mounted in read-only mode to protect system integrity and security. This means you can't directly write or modify system files on the device. Executing the remount operation allows you to switch the file system to a writable mode, allowing file transfers or modifications. Since remount requires root permissions, you must first execute the root command, followed by remount.

# Execute root
C:\Users\win>adb root
restarting adbd as root
# Execute remount
C:\Users\win>adb remount
Using overlayfs for /system
Using overlayfs for /vendor
Using overlayfs for /odm
Using overlayfs for /product
Using overlayfs for /system_ext
Now reboot your device for settings to take effect
remount succeeded

Now, you can use the adb push command to transfer a file from your computer to the Android device. Example:

C:\Users\win>adb push C:\Users\win\Downloads\chrome.apk /data
C:\Users\win\Downloads\chrome.apk: 1 file pushed, 0 skipped. 48.3 MB/s (236058891 bytesin4.661s)
#To check if the file was successfully transferred:
C:\Users\win>adb shell
rk3566_tspi:/# ls /data/c
cache/      chrome.apk#You will find the file in the directory

Copy Files from Device to Computer

adb pull

"adb pull device_directory file_save_directory"

# Create a test file on the device:
rk3566_tspi:/data# echo "tispi" > pulldemo.txt
# Exit the shell terminal
rk3566_tspi:/data# exit
# Now start testing, we will copy the pulldemo.txt file from /data/ to C:\Users\win\Downloads on the computer:
C:\Users\win>adb pull /data/pulldemo.txt C:\Users\win\Downloads
# The transfer rate and time will show, indicating a successful transfer:
/data/pulldemo.txt: 1 file pulled, 0 skipped. 0.0 MB/s (6 bytes in 0.002s)

Check the file in your Downloads folder:

View Device Logs

The following commands are very useful when debugging code and analyzing issues, as logs often help pinpoint problems. If you're discussing issues, it's helpful to share the logcat and dmesg logs.

• logcat: Responsible for Android-level log output:

adb logcat

• dmesg: Responsible for Linux-level log output:

adb dmesg

Enter Upgrade Mode

adb reboot loader