> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# HarmonyOS environment setup

Midscene connects to and controls HarmonyOS NEXT devices through HarmonyOS Device Connector (HDC), supporting UI automation across native apps, atomic services, and system interfaces.

This guide prepares the HarmonyOS environment: install HDC and connect the device. Playground, Midscene Test, and the JavaScript SDK all use this connection.

## Connect the device through HDC {#connect-device}

Midscene uses `hdc` on your computer to communicate with the target HarmonyOS NEXT device. If `hdc` is already installed and your device is connected, skip directly to [Verify the device connection](#verify-device-connection).

### Install HDC

HDC (HarmonyOS Device Connector) is the official command-line tool for communicating with HarmonyOS devices. Install it using either of the following methods:

- Via [DevEco Studio](https://developer.huawei.com/consumer/en/deveco-studio/) (recommended)
- Via the standalone [HarmonyOS Command Line Tools](https://developer.huawei.com/consumer/en/download/)

Run the following command to verify the installation:

```bash
hdc version
```

A version number in the terminal output confirms a working installation.

:::info Configuring the HDC path

If `hdc` is not in your system `PATH`, set the `HDC_HOME` environment variable to the directory containing the `hdc` executable:

```bash
export HDC_HOME=/path/to/hdc/directory
```

:::

### Enable debugging and connect the device

1. On your HarmonyOS device, open **Settings > System > Developer options** and enable **USB debugging**.
2. Connect the device to your computer using a USB cable that supports data transfer.
3. Keep the device unlocked and accept the debugging authorization prompt on the screen.

### Verify the device connection {#verify-device-connection}

Run the following command to check the connection status:

```bash
hdc list targets
```

A device ID in the output confirms that the device is connected and ready:

```log
0123456789ABCDEF
```

If multiple devices are connected, note the target device ID so you can select it in Playground or your project configuration. If the output is empty or `[Empty]`, check the USB cable, USB connection mode, **USB debugging** toggle, and the authorization prompt on the device.

## Verify {#verify}

When `hdc list targets` lists the target device, verify the environment in Playground. Open [Get started](/get-started.md?platform=harmonyos\&scene=playground), where HarmonyOS and Playground are already selected, choose how to connect a model, and follow the steps to run one `aiAct` action and one `aiAssert` assertion. A passing assertion confirms that the HDC connection, screen capture, touch input, and model calls work together.

## FAQ {#faq}

### Keyboard is not dismissed or the page navigates back after typing

See the [HarmonyOS JavaScript SDK guide](/sdk/harmonyos.md#keyboard-is-not-dismissed-or-the-page-navigates-back-after-typing).

### How do I specify a custom HDC path?

Point the `HDC_HOME` environment variable to the directory containing the `hdc` executable:

```bash
export HDC_HOME=/path/to/hdc/directory
```

For configuring the path via constructor options in code, see the [HarmonyOS JavaScript SDK guide](/sdk/harmonyos.md#how-do-i-specify-a-custom-hdc-path).