Skip to content

devicebase/devicebase-temporary

Repository files navigation

Devicebase

npm version

JavaScript/TypeScript SDK & CLI for DeviceBase — remote Android, HarmonyOS, and iOS device automation via HTTP API.

Features

  • CLI — Cross-platform command-line tool for device control
  • SDK — Full-featured TypeScript client for programmatic device automation
  • WebSocket — Real-time screen streaming (Minicap) and touch control (Minitouch)

Requirements

  • Node.js >= 18.0.0 (native fetch and WebSocket)

Installation

As a CLI tool (global install)

npm install -g devicebase

As an SDK dependency

npm install devicebase

CLI Usage

Set environment variables before using the CLI:

export DEVICEBASE_API_KEY=your_api_key
export DEVICEBASE_BASE_URL=https://api.devicebase.cn  # optional, defaults to this

Most commands require the -s <serial> flag to specify the target device. The list-devices command is an exception.

Device Management

# List all devices (no -s flag required)
devicebase list-devices

# Filter by keyword (brand/model/serial/name)
devicebase list-devices --keyword "iPhone"

# Filter by state (busy/free/offline)
devicebase list-devices --state free

# Combine filters with limit
devicebase list-devices --keyword "Samsung" --state busy --limit 20

Touch Interactions

# Tap at coordinates
devicebase -s <serial> tap 100,200

# Double tap
devicebase -s <serial> double-tap 100,200

# Long press
devicebase -s <serial> long-press 100,200

# Swipe from (x1,y1) to (x2,y2)
devicebase -s <serial> swipe 100,200,300,400

Navigation

# Press back button
devicebase -s <serial> back

# Press home button
devicebase -s <serial> home

App Management

# Launch an app by name
devicebase -s <serial> launch-app com.example.app

# Get the current foreground app
devicebase -s <serial> current-app

Text Input

# Input text
devicebase -s <serial> input "Hello World"

# Clear text field
devicebase -s <serial> clear-text

Device Information

# Get device info
devicebase -s <serial> device-info

# Dump UI hierarchy (accessibility tree)
devicebase -s <serial> dump-hierarchy

# Take a screenshot (outputs to stdout)
devicebase -s <serial> screenshot

# Save screenshot to a file
devicebase -s <serial> screenshot -o screenshot.jpg

Global Flags

Flag Short Description
--serial -s Device serial number
--help -h Show help
--version Show version

SDK Usage

import { DeviceBaseClient } from 'devicebase'

const client = new DeviceBaseClient({
  apiKey: 'your-api-key',
  serial: 'device-serial-number',
})

// Get device info
const deviceInfo = await client.getDeviceInfo()

// Take a screenshot
const screenshot = await client.getScreenshot()

// Touch operations
await client.tap(100, 200)
await client.doubleTap(100, 200)
await client.longPress(100, 200)
await client.swipe(100, 500, 100, 100)

// Navigation
await client.back()
await client.home()

// Launch an app
await client.launchApp('com.tencent.mm')

// Text input
await client.inputText('hello world')
await client.clearText()

// Get current foreground app
const appInfo = await client.getCurrentApp()

// Dump UI hierarchy
const hierarchy = await client.dumpHierarchy()

Configuration

const client = new DeviceBaseClient({
  serial: 'device-serial', // Required: device serial number
  apiKey: 'your-api-key', // Optional: defaults to DEVICEBASE_API_KEY env var
  baseUrl: 'https://api.devicebase.cn', // Optional: API base URL
  timeout: 30000, // Optional: request timeout in ms (default: 30000)
})

Environment variables:

  • DEVICEBASE_API_KEY — API key for authentication
  • DEVICEBASE_BASE_URL — API base URL (default: https://api.devicebase.cn)

WebSocket Streaming

Screen Streaming (Minicap)

const minicap = client.minicapClient()

for await (const frame of minicap.streamFrames()) {
  // frame is a Buffer containing JPEG image data
  console.log('Frame:', frame.length, 'bytes')
}

// Or use the convenience method:
for await (const frame of client.streamMinicap()) {
  console.log('Frame:', frame.length, 'bytes')
}

Touch Control (Minitouch)

const minitouch = client.minitouchClient()
await minitouch.connect()

// Tap
await minitouch.tap(100, 200)

// Swipe with custom duration and steps
await minitouch.swipe(100, 500, 100, 100, 300, 10)

// Low-level touch events
await minitouch.touchDown(0, 100, 200)
await minitouch.commit()
await minitouch.touchUp(0)
await minitouch.commit()

await minitouch.close()

API Reference

DeviceBaseClient

Method Returns Description
getDeviceInfo() Promise<DeviceInfo> Get device status and hardware info
tap(x, y) Promise<OperationResult> Single tap at coordinates
doubleTap(x, y) Promise<OperationResult> Double tap at coordinates
longPress(x, y) Promise<OperationResult> Long press at coordinates
swipe(x1, y1, x2, y2) Promise<OperationResult> Swipe gesture
back() Promise<OperationResult> Press back button
home() Promise<OperationResult> Press home button
launchApp(appName) Promise<OperationResult> Launch app by package name
getCurrentApp() Promise<AppInfo> Get foreground app info
inputText(text) Promise<OperationResult> Type text into focused field
clearText() Promise<OperationResult> Clear text in focused field
dumpHierarchy() Promise<HierarchyInfo> Get UI element tree
getScreenshot() Promise<ArrayBuffer> Screenshot as JPEG bytes
downloadScreenshot() Promise<ArrayBuffer> Download screenshot as attachment
minicapClient() MinicapClient Create screen streaming WebSocket client
minitouchClient() MinitouchClient Create touch control WebSocket client
streamMinicap() AsyncGenerator<Buffer> Stream JPEG frames

Development

# Install dependencies
npm install

# Build SDK + CLI
npm run build:all

# Build SDK only
npm run build

# Build CLI only
npm run build:bin

# Type check
npm run typecheck

# Run tests
npm test

License

MIT

About

Devicebase SDK & CLI

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors