DCP message reference - Axilio

Every DCP method, grouped by capability domain. A command is { "id", "method", "params" }; the response echoes the id and carries result on success or error on failure. Coordinates are pixels in the phone’s native resolution (read it from Device.info). A phone advertises the methods it supports in the handshake — check capabilities before you depend on a method rather than assuming the whole surface.

Protocol

`Protocol.handshake`

Negotiate the protocol and discover what the phone supports. Send it once, right after you open the socket, and repeat it after every reconnect before sending more work.

{ "id": 1, "method": "Protocol.handshake", "params": {} }

Param	Type	Required	Description
`client_version`	string	No	Reserved informational field; the phone currently accepts but does not act on it.
`min_protocol`	integer	No	Informational; the phone reports its own version in the result.

Result

Field	Type	Description
`protocol_version`	integer	The protocol version the phone speaks.
`device`	object	The device descriptor, same shape as `Device.info`.
`domains`	string[]	The capability domains this phone advertises, e.g. `["Device", "Keyboard", "Locator", "Protocol", "Screen", "Touch"]`.
`capabilities`	string[]	The exact method names this phone answers, e.g. `["Touch.tap", "Screen.observe", ...]`.

Device

`Device.info`

The static device descriptor — read it to size taps and swipes without a screenshot round trip.

{ "id": 2, "method": "Device.info", "params": {} }

Result

Field	Type	Description
`device_id`	string	Stable id for this phone.
`platform`	string	OS family — `"android"`.
`form_factor`	string	Physical class — `"phone"`.
`input_modalities`	string[]	Interaction classes the phone accepts — `["touch", "keyboard"]`.
`screen_width`	integer	Native width in pixels.
`screen_height`	integer	Native height in pixels.
`model`	string	Best-effort model name; may be empty.
`os_version`	string	Best-effort OS version; may be empty.

Touch

`Touch.tap`

Tap a pixel.

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

Param	Type	Required	Description
`x`	integer	Yes	X coordinate in pixels.
`y`	integer	Yes	Y coordinate in pixels.
`idempotencyKey`	string	No	Unique key for this logical input. Reuse it only when resending the same command after reconnect.

Result — an empty object {}.

`Touch.longPress`

Press and hold a pixel.

{ "id": 4, "method": "Touch.longPress", "params": { "x": 540, "y": 1180, "duration_ms": 800 } }

Param	Type	Required	Description
`x`	integer	Yes	X coordinate in pixels.
`y`	integer	Yes	Y coordinate in pixels.
`duration_ms`	integer	No	Hold duration in milliseconds.
`idempotencyKey`	string	No	Unique key for this logical input. Reuse it only when resending the same command after reconnect.

Result — an empty object {}.

`Touch.swipe`

Swipe from one pixel to another.

{ "id": 5, "method": "Touch.swipe", "params": { "x1": 540, "y1": 1600, "x2": 540, "y2": 400, "duration_ms": 300 } }

Param	Type	Required	Description
`x1`, `y1`	integer	Yes	Start pixel.
`x2`, `y2`	integer	Yes	End pixel.
`duration_ms`	integer	No	Swipe duration in milliseconds.
`idempotencyKey`	string	No	Unique key for this logical input. Reuse it only when resending the same command after reconnect.

Result — an empty object {}.

Keyboard

`Keyboard.typeText`

Type a string into the focused field.

{ "id": 6, "method": "Keyboard.typeText", "params": { "text": "hello" } }

Param	Type	Required	Description
`text`	string	Yes	The text to type.
`idempotencyKey`	string	No	Unique key for this logical input. Reuse it only when resending the same command after reconnect.

Result — an empty object {}.

`Keyboard.keyPress`

Press a supported named key. Raw DCP accepts enter and capslock; the CLI and SDKs expose Enter as their customer-facing named key. Use Keyboard.typeText for printable text.

{ "id": 7, "method": "Keyboard.keyPress", "params": { "key": "enter" } }

Param	Type	Required	Description
`key`	string	Yes	`"enter"` or `"capslock"`. The server rejects other values.
`idempotencyKey`	string	No	Unique key for this logical input. Reuse it only when resending the same command after reconnect.

Result — an empty object {}.

Screen

`Screen.screenshot`

Capture the current frame as a PNG.

{ "id": 8, "method": "Screen.screenshot", "params": {} }

Result

Field	Type	Description
`png_base64`	string	The frame as a base64-encoded PNG.

`Screen.observe`

Read the screen — its text and icons, with bounding boxes.

{ "id": 9, "method": "Screen.observe", "params": { "ocr_engine": "free" } }

Param	Type	Required	Description
`ocr_engine`	string	No	`"free"` or `"premium"`. Defaults to `free`.

Result

Field	Type	Description
`texts`	object[]	Detected text: `text`, `bbox` (`x`, `y`, `width`, `height`), `confidence`.
`icons`	object[]	Detected icons: `bbox`, `confidence`.
`hash`	string	Content hash of the frame; unchanged means the screen didn’t change.
`width`, `height`	integer	Frame dimensions in pixels.
`captured_at`	integer	Frame timestamp, epoch milliseconds.

Locator

Each Locator method finds its target on the current frame, waits until the target is ready, then acts or answers, all on the phone side in one round trip. A locator is an object of target fields that combine as AND:

Field	Type	Description
`text`	string	Visible text; a case-insensitive substring unless `exact` is true.
`exact`	boolean	Require an exact, case-sensitive text match.
`query`	string	Plain-English description, read by a vision model.
`within`	locator	Refine to a match inside this locator’s match.
`has`	locator	Refine to a match that contains this locator’s match.
`nth`	integer	Pick the nth match in reading order, zero-based.

Plain text resolves by OCR; anything more uses one vision-model call. The contract also defines role, name, id, states, and platform. They need the phone’s accessibility tree, which phones don’t expose yet, so they fail with StrategyUnavailable. Every Locator method accepts these params alongside its own:

Param	Type	Required	Description
`locator`	object	Yes (except `Locator.press`)	The target, as above.
`timeoutMs`	integer	No	Budget for the whole call, waiting included. Default `5000`, maximum `60000`. Not on `Locator.count`.
`ocrEngine`	string	No	`"free"` or `"premium"`.
`model`	string	No	A vision model id; defaults to an automatic choice.

When the target never becomes ready within timeoutMs, the call fails with ActionTimeout. Most results are a LocatorResult:

Field	Type	Description
`resolvedBy`	string	How the target was found: `"ocr"` or `"vlm"`.
`bounds`	object	Where the target was when the phone acted: `x`, `y`, `width`, `height`.
`tookMs`	integer	Time on the phone, waiting included.
`modelName`	string	The vision model that resolved the target, when `resolvedBy` is `"vlm"`.

`Locator.tap`

Wait for the target, then tap its center.

{ "id": 10, "method": "Locator.tap", "params": { "locator": { "query": "the search icon" } } }

Also takes idempotencyKey. Result — a LocatorResult.

`Locator.fill`

Wait for the target, tap it to focus, then type text into it.

{ "id": 11, "method": "Locator.fill", "params": { "locator": { "text": "Search" }, "text": "axilio" } }

Requires text; also takes idempotencyKey. Result — a LocatorResult.

`Locator.press`

Press a named key: "enter" or "capslock". With a locator, the target is found, waited for, and focused first; without one, the key goes to whatever has focus.

{ "id": 12, "method": "Locator.press", "params": { "locator": { "text": "Search" }, "key": "enter" } }

Requires key; also takes idempotencyKey. Result — a LocatorResult; resolvedBy and bounds are present only when the press carried a locator.

`Locator.waitFor`

Wait until the target reaches a state, re-checking each fresh frame. One call replaces a client-side polling loop.

{ "id": 13, "method": "Locator.waitFor", "params": { "locator": { "text": "Loading" }, "state": "hidden", "timeoutMs": 30000 } }

state is "visible" (the default) or "hidden". Result — a LocatorResult; resolvedBy and bounds are absent for "hidden".

`Locator.boundingBox`

Wait for the target, then return where it is.

{ "id": 14, "method": "Locator.boundingBox", "params": { "locator": { "text": "Photo" } } }

Result — a LocatorResult.

`Locator.text`

Wait for the target, then return its recognized text.

{ "id": 15, "method": "Locator.text", "params": { "locator": { "query": "the order total" } } }

Result — a LocatorResult plus text (string).

`Locator.count`

Count the matches on the current screen, zero included. Never waits.

{ "id": 16, "method": "Locator.count", "params": { "locator": { "text": "Add to cart" } } }

Result — count (integer), resolvedBy, and tookMs. Customer-billed cost is available from the session’s retained Telemetry response, not from the DCP result.

Errors

A failed command answers with error instead of result:

{
  "id": 3,
  "error": {
    "code": -32602,
    "message": "x is required",
    "data": { "kind": "InvalidArgs", "retryable": false }
  }
}

data.kind is the machine-readable classification and data.retryable says whether retrying the same command could succeed:

Kind	Code	Retryable	Meaning
`UnknownOp`	-32601	No	The phone doesn’t recognize the method.
`InvalidArgs`	-32602	No	The params failed validation.
`Internal`	-32603	No	An unclassified server-side failure.
`NoAllocation`	-32001	No	The session has no active phone allocation.
`NotConnected`	-32002	No	The server couldn’t reach the phone.
`DeviceOffline`	-32004	Yes	The phone is transiently unavailable.
`Timeout`	-32006	Yes	The command exceeded its deadline.
`Unauthorized`	-32007	No	The session credential was rejected.
`Canceled`	-32008	No	The command was canceled.
`ActionTimeout`	-32009	No	A Locator target never became ready within `timeoutMs`.
`StrategyUnavailable`	-32010	No	The locator needs a resolver this session doesn’t have, such as the accessibility tree.

Next steps

Drive a phone with raw DCP

A worked example, socket to first command.

Protocol overview

How the wire is framed and why.

Reconnect and resume

Close classes, cursor replay, resync, and idempotency keys.

Use the SDK instead

The ergonomic driver over these methods.

Vision models

Model ids and pricing for Locator descriptions.