For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /platforms/harmonyos.md.
  • English

      • 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

      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.

      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:

      Run the following command to verify the installation:

      hdc version

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

      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:

      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

      Run the following command to check the connection status:

      hdc list targets

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

      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

      When hdc list targets lists the target device, verify the environment in Playground. Open Get started, 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

      Keyboard is not dismissed or the page navigates back after typing

      See the HarmonyOS JavaScript SDK guide.

      How do I specify a custom HDC path?

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

      export HDC_HOME=/path/to/hdc/directory

      For configuring the path via constructor options in code, see the HarmonyOS JavaScript SDK guide.