droidline

Quick start

Pair a phone with your PC and send your first commands from the shell, Python, Node.js or HTTP, in about five steps.

This page assumes the server, the app and its permissions are already installed. If not, do Installation first; it takes about fifteen minutes. You need the PC and the phone on the same Wi-Fi for this page.

1. Start the server

In a terminal on the PC:

droidline serve

Leave it running. Everything below happens in a second terminal.

2. Pair the phone

Pairing introduces the phone and the PC to each other once. They exchange keys, and from then on they recognize each other and encrypt everything between them. You do this once per phone.

  1. On the PC, run:

    droidline pair

    A QR code appears in the terminal. It is valid for 10 minutes and pairs one phone.

  2. On the phone, open Droidline, go to the Pair tab and tap Scan QR.

  3. Point the camera at the terminal. The app shows Paired with and the name of your PC.

Use this when the phone has no camera or the QR code does not scan.

  1. On the phone, open Droidline, go to the Pair tab and tap Pair on this Wi-Fi.

  2. The app looks for your PC on the network. Choose it if more than one shows up. The app then shows a 6-digit code, valid for 5 minutes.

  3. On the PC, type the code. --name gives the phone a short name you will use later:

    droidline pair 482913 --name shelf-01

3. Check that the phone is online

droidline devices
NAME      ID        MODEL     ANDROID  STATE   ROUTE  MISSING
shelf-01  k7d2q9xa  SM-S921N  14       online  lan    notif,vpn
  • STATE should be online.
  • ROUTE shows how the phone reaches the PC. lan means directly over your Wi-Fi.
  • MISSING lists permissions that are still off on the phone: a11y (accessibility service), ime (Droidline keyboard), notif (notification access), vpn (VPN permission) and capture (screen capture, asked only on Android 9 and 10). Only a11y and ime are required, so notif,vpn here is fine.

4. Send your first commands

Every example below opens the Settings app on the phone, taps an entry, and reads back which screen is showing. Pick the tab for the language you want to use.

droidline launch com.android.settings
droidline touch text "Network & internet"
droidline current
from droidline import connect

d = connect()                        # the only phone that is online
d.launch("com.android.settings")     # open Settings
d.touch("text", "Network & internet")
print(d.current())                   # {'package': 'com.android.settings', 'activity': ...}
import { connect } from "droidline";

const d = await connect();                    // the only phone that is online
await d.launch("com.android.settings");      // open Settings
await d.touch("text", "Network & internet");
console.log(await d.current());              // { package: 'com.android.settings', activity: ... }
curl -s -X POST localhost:8780/devices/_/launch \
  -H 'content-type: application/json' -d '{"package":"com.android.settings"}'

curl -s -X POST localhost:8780/devices/_/touch \
  -H 'content-type: application/json' -d '{"by":"text","value":"Network & internet"}'

curl -s -X POST localhost:8780/devices/_/current -H 'content-type: application/json'

Save the Python example as first.py and run it with python first.py, or save the Node.js example as first.mjs and run it with node first.mjs. The .mjs ending tells Node.js the file uses import.

5. See what is on the screen

To act on a screen, you need to know how Droidline sees it. dump saves the screen as a tree of elements, and screenshot saves a picture:

droidline dump screen.json
droidline screenshot screen.png
d.dump("screen.json")
d.screenshot("screen.png")
await d.dump("screen.json");
await d.screenshot("screen.png");
curl -s -X POST localhost:8780/devices/_/dump -H 'content-type: application/json' > screen.json
curl -s localhost:8780/devices/_/screenshot.png -o screen.png

Open screen.json and search for the words you see on the phone. Each element has a text, an id and a desc; those are the values you pass to touch. Finding elements explains how to choose between them.

What next