Device Control Protocol

Every phone you allocate exposes a control_url: a single WebSocket that drives the phone. The Device Control Protocol (DCP) is what rides on that socket. The Python and Go mobile drivers speak it for you, but the socket is yours — you can open it directly and drive a phone from any language with a WebSocket client. DCP is to phones what the Chrome DevTools Protocol is to browsers: a small, literal message protocol you can drive raw. Commands go down, results and notifications come back, one phone per connection.

Two layers, one protocol

The SDK is the friendly path. MobileDriver adds plain-English selectors, waiting, and retries on top of DCP. Reach for it first — most code should.
The raw protocol is the power path. Open control_url yourself when you work outside Python, embed control in your own runtime, or want the exact frames on the wire with nothing in between.

Both drive the same phone through the same socket. The mobile drivers implement their high-level actions by sending these DCP methods.

How the wire looks

DCP is JSON-RPC framed like the Chrome DevTools Protocol — the frame is the whole payload, at the top level, with no envelope. A command looks like this:

{ "id": 1, "method": "Touch.tap", "params": { "x": 540, "y": 1180 } }

The phone returns a response with the same id:

{ "id": 1, "result": {} }

Each command carries an id; its response echoes that id. A method name is Domain.method — Touch.tap, Screen.observe, Device.info. A phone advertises the domains it supports in the handshake, so you discover its capabilities instead of assuming them.

Connection lifetime

The phone session outlives an individual WebSocket. The Python and Go mobile drivers reconnect automatically. If you manage a raw client, classify socket closes, resume with the opaque cursor the server provides, repeat the handshake, and reuse idempotency keys when you resend an ambiguous input command. See Reconnect and resume for the complete raw client contract.

What DCP drives

DCP is a phone protocol. A phone advertises these capability domains:

Domain	What it does
`Protocol`	Handshake — negotiate the protocol version and discover capabilities.
`Device`	Read the static device descriptor (screen size, platform, input modalities).
`Screen`	Screenshot, observe (OCR + icons), and find an element by description.
`Touch`	Tap, long-press, and swipe at pixel coordinates.
`Keyboard`	Type text and press named keys.

Next steps

Drive a phone with raw DCP

Open the socket, handshake, and send your first command.

Message reference

Every method, its params, and its result.

Reconnect and resume

Recover from a dropped socket without a gap or double input.

Get a phone

Allocate a phone and read its control_url.

Use the SDK instead

The ergonomic layer over DCP.

Overview