adb_dart #

A lightweight Dart client for interacting with Android devices through ADB (Android Debug Bridge).

This package provides a simple and intuitive API to manage Android devices, install applications, read logs, and more, directly from your Dart applications.

Features #

• Device Management
  • List connected Android devices with detailed information
  • Access device system properties
• Package Management
  • Install APK files on devices
  • Retrieve installed third-party packages
• Logcat
  • Stream logcat output with filtering options (by level and process ID)
  • Clear logcat buffer
• File System Operations
  • List files and directories on the device
  • Upload and download files between device and local filesystem
  • Create directories on the device
  • Delete files and directories
  • Support for app-specific private directories using run-as
• Logging
  • Customizable logging with the AdbLogger interface
  • Default console logger included

Prerequisites #

You need to have ADB installed on your system. You can get it from:

• Android SDK Platform Tools
• Or install Android Studio which includes ADB

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  adb_dart: ^1.0.0

Then run:

dart pub get

Usage #

Initialize the client #

import 'package:adb_dart/adb_dart.dart';

// Provide the path to your adb executable
final adbClient = AdbClient(adbExecutablePath: '/path/to/adb');

// With custom logger
final adbClient = AdbClient(
  adbExecutablePath: '/path/to/adb',
  logger: ConsoleLogger(), // Your custom AdbLogger implementation
);

// On macOS/Linux with Android Studio:
// final adbClient = AdbClient(adbExecutablePath: '~/Library/Android/sdk/platform-tools/adb');

// On Windows with Android Studio:
// final adbClient = AdbClient(adbExecutablePath: r'C:\Users\YourName\AppData\Local\Android\Sdk\platform-tools\adb.exe');

List connected devices #

final devices = await adbClient.listConnectedDevices();

for (final device in devices) {
  print('Device: ${device.name}');
  print('Manufacturer: ${device.manufacturer}');
  print('ID: ${device.deviceId}');
}

Install an APK #

final apkFile = File('/path/to/your/app.apk');
await adbClient.installApplication(apkFile, deviceId);

List installed packages #

final packages = await adbClient.getAllPackages(deviceId);
print('Installed packages: $packages');

Get device properties #

final properties = await adbClient.getProperties(deviceId);
print('Android version: ${properties['ro.build.version.release']}');
print('Device model: ${properties['ro.product.model']}');

Listen to logcat #

// Clear previous logs
await adbClient.clearLogcat(deviceId);

// Listen to all logs
adbClient.listenLogcat(deviceId).listen((lines) {
  for (final line in lines) {
    print(line);
  }
});

// Listen to specific log level
adbClient.listenLogcat(
  deviceId,
  level: LogcatLevel.error,
).listen((lines) {
  for (final line in lines) {
    print('Error: $line');
  }
});

// Listen to specific process
adbClient.listenLogcat(
  deviceId,
  processId: 12345,
).listen((lines) {
  for (final line in lines) {
    print(line);
  }
});

File system operations #

// List files in a directory
final files = await adbClient.listFiles('/sdcard/Download', deviceId);
for (final file in files) {
  print('${file.name} - ${file.type.name} - ${file.size} bytes');
}

// Create a directory
await adbClient.createDirectory('/sdcard/', 'MyFolder', deviceId);

// Upload a file to the device
await adbClient.uploadFile(
  'local/file.txt',
  '/sdcard/MyFolder/file.txt',
  deviceId,
);

// Download a file from the device
await adbClient.downloadFile(
  '/sdcard/MyFolder/file.txt',
  'downloaded_file.txt',
  deviceId,
);

// Delete a file or directory
await adbClient.deleteFile('/sdcard/MyFolder', deviceId);

// Access app-specific private directories
final appFiles = await adbClient.listFiles(
  '/data/data/com.example.app/files',
  deviceId,
  packageName: 'com.example.app', // Required for private directories
);

// Upload to app's private directory
await adbClient.uploadFile(
  'config.json',
  'files/config.json', // Relative path within app's directory
  deviceId,
  packageName: 'com.example.app',
);

Complete Example #

import 'dart:io';
import 'package:adb_dart/adb_dart.dart';

Future<void> main() async {
  // Initialize ADB client
  final adbClient = AdbClient(adbExecutablePath: './platform-tools/adb');

  // List connected devices
  final devices = await adbClient.listConnectedDevices();

  if (devices.isEmpty) {
    print('No devices connected');
    return;
  }

  final device = devices.first;
  print('Using device: ${device.name} (${device.deviceId})');

  // Clear logcat
  await adbClient.clearLogcat(device.deviceId);

  // Listen to logcat
  adbClient.listenLogcat(device.deviceId).listen((lines) {
    for (final line in lines) {
      print(line);
    }
  });

  // Install an application
  final apkFile = File('my_app.apk');
  if (apkFile.existsSync()) {
    await adbClient.installApplication(apkFile, device.deviceId);
    print('Application installed successfully');
  }
}

API Reference #

AdbClient #

Constructor

• AdbClient({required String adbExecutablePath, AdbLogger? logger}) - Creates a new ADB client instance with optional custom logger

Device Methods

• Future<Iterable<AndroidDevice>> listConnectedDevices() - Lists all connected devices
• Future<Map<String, String>> getProperties(DeviceId deviceId) - Retrieves device system properties

Package Methods

• Future<void> installApplication(File apkFile, DeviceId deviceId) - Installs an APK on a device
• Future<Iterable<String>> getAllPackages(DeviceId deviceId) - Gets all third-party packages installed

Logcat Methods

• Stream<Iterable<String>> listenLogcat(DeviceId deviceId, {LogcatLevel? level, int? processId}) - Streams logcat output
• Future<void> clearLogcat(DeviceId deviceId) - Clears the logcat buffer

File System Methods

• Future<Iterable<FileEntry>> listFiles(String path, DeviceId deviceId, {String? packageName}) - Lists files and directories
• Future<void> createDirectory(String path, String name, DeviceId deviceId, {String? packageName}) - Creates a directory
• Future<void> uploadFile(String localFilePath, String destinationPath, DeviceId deviceId, {String? packageName}) - Uploads a file to the device
• Future<void> downloadFile(String filePath, String destinationPath, DeviceId deviceId, {String? packageName}) - Downloads a file from the device
• Future<void> deleteFile(String filePath, DeviceId deviceId, {String? packageName}) - Deletes a file or directory

Models #

FileEntry

Represents a file or directory on the Android device:

• FileType type - Type of the entry (file, directory, symlink, or unknown)
• String name - Name of the file or directory
• String permissions - Unix-style permissions (e.g., "drwxr-xr-x")
• int? size - Size in bytes (null for directories)
• DateTime? date - Last modification date
• String? owner - Owner user
• String? group - Owner group
• int? links - Number of hard links
• String? symlinkTarget - Target path if this is a symlink

FileType

Enumeration of file types:

• FileType.file - Regular file
• FileType.directory - Directory
• FileType.symlink - Symbolic link
• FileType.unknown - Unknown type

LogcatLevel

Available log levels for filtering:

• LogcatLevel.verbose
• LogcatLevel.debug
• LogcatLevel.info
• LogcatLevel.warning
• LogcatLevel.error
• LogcatLevel.fatal

Logging #

AdbLogger Interface

Implement this interface to create custom loggers:

abstract class AdbLogger {
  void debug(String message);
  void info(String message);
  void error(String message, {Object? error, StackTrace? stackTrace});
}

DefaultLogger

A built-in logger that outputs to the console. Used by default if no logger is provided.

Exceptions #

All exceptions extend AdbException:

• AdbInitializationException - Thrown when ADB executable is not found
• AdbDeviceException - Thrown when device operations fail
• AdbPackageException - Thrown when package operations fail
• AdbPropertyException - Thrown when property retrieval fails
• AdbLogcatException - Thrown when logcat operations fail
• AdbInstallationException - Thrown when APK installation fails

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

Issues #

If you encounter any issues or have suggestions, please file them in the issue tracker.

License #

This project is licensed under the MIT License - see the LICENSE file for details.