Debug a Wear OS app

To debug your Wear OS app on a physical watch, connect your development machine to the watch using Wi-Fi or Bluetooth. Alternatively, if your watch has a USB port, connect using USB.

You can also test workflows that span multiple devices, such as a watch and a phone, if your app requires this support. To learn more about how to set up a connection for testing, visit connect a watch to a phone.

Note: If you don't have a physical watch, you can also test and run your app on an emulator in Android Studio.

Update to the latest version of Wear OS

To help verify that your app behaves as expected on the latest software, check that your test device is running the most up-to-date version of Wear OS that your device supports.

To check for a system update on your test device, complete these steps:

  1. Connect the device to a Wi-Fi network.
  2. Start charging the device.
  3. Wait for the device's battery to charge to 50% or higher.

  4. On your test device, navigate to Settings > System > System updates.

    If a system update is available, it'll be downloaded and installed onto your test device.

Install a specific version of Wear OS (optional)

If your app's test case depends on a specific version of Wear OS, you can flash a software image onto watches that support a USB data connection. For example, you can flash a factory image or a full OTA image onto a Google Pixel Watch 3 or Google Pixel Watch 2 device.

Enable developer options on your watch

Before you can debug on your watch, enable developer options. You only need to do this one time. Developer options remain enabled until you disable them. To enable developer options, do the following:

  1. Open the watch's Settings.
  2. Tap System > About > Versions.
  3. Tap the Build number item seven times.
  4. A message appears confirming that you are now a developer.

Debug over Wi-Fi

Before you begin, enable developer options on the watch as described previously.

Connect the watch to a Wi-Fi network

  1. Open the watch's Settings.
  2. Tap Connectivity > Wi-Fi.
  3. Choose a network and enter its password if necessary.

    Note: The watch and your development machine must be connected to the same network. Not all access points are suitable. You may need to use an access point whose firewall is configured properly to support adb.

Enable Wi-Fi debugging

  1. Open the watch's Settings.
  2. Tap Developer options > Debug over Wi-Fi.
  3. After a moment, the screen displays the watch's IP address, such as 192.168.1.100. You need this for the next step, so make a note of it.

Pair the debugger to the watch

  1. On your Wear OS device, find the wireless debugging options in system settings. Select Pair new device.
  2. Note the Wi-Fi pairing code and the IP address & port.
  3. In a terminal window on your development machine, type the following command: 
    adb pair IP_ADDRESS:PORT
  4. When prompted, enter the Wi-Fi pairing code from step 2. The terminal will output whether pairing was successful. As an example: 
    Enter pairing code: 123456
Successfully paired to 192.168.1.100:5555
After pairing, the host computer appears in the list of Paired devices on your Wear OS device's Wireless Debugging screen.

Connect the debugger to the watch

  1. Connect your watch and development machine to the same network.

  2. Connect the debugger to the watch using the watch's IP address and a port number. For example, if the IP address is 192.168.1.100 and the port number is 5555, the adb connect command and its response look like this: 

    adb connect 192.168.1.100:5555
connected to 192.168.1.100:5555

The watch is now connected to the debugger and you are ready to start debugging. Send adb commands to the watch using the -s flag, specifying the watch's IP address and the port number:

adb -s 192.168.1.100:5555 <command>

If you are not using the emulator and have only one device connected for debugging, you don't need to specify the address:

adb <command>

Debug over Bluetooth

Note: Bluetooth debugging works only for Android-paired watches running Wear OS 2.

Before you begin, pair the watch and phone and enable developer options on the watch as described previously. Check that developer options are enabled on the phone by opening the phone's Settings menu and looking for Developer Options. If necessary, enable developer options on the phone.

Enable USB debugging on the phone

  1. Open the phone's Settings menu.
  2. Select Developer Options and enable USB debugging.

Enable ADB or Bluetooth debugging on the watch

  1. Open the watch's Settings menu.
  2. Scroll to Developer Options.
  3. Confirm that ADB debugging is enabled.
  4. Enable Debug over Bluetooth.

Enable Bluetooth debugging on the phone

  1. On the phone, open the Wear OS companion app.
  2. Scroll to Advanced Settings and tap to view the Advanced Settings options.
  3. Enable Debugging over Bluetooth. The following status message appears under the option: 
    Host: disconnected
Target: connected

At this point the development machine—the host—is not communicating with the watch—the target. You need to complete the link.

Note: You can only debug with one device at a time. If you have multiple watches paired, Bluetooth debugging is only enabled with the device selected on the main screen.

Connect the debugger to the watch

In this final step, you use everything: the debugger, the phone, and the watch.

  1. Connect the phone to your development machine with a USB cable.
  2. Run these two commands in the debugger: 
    adb forward tcp:4444 localabstract:/adb-hub
adb connect 127.0.0.1:4444

    Note: You must use the IP address 127.0.0.1. Use any available port on your development machine, and use the same port in both commands. In this example, the port is 4444.

  3. After you enter the connect command, the watch asks you to confirm that you are allowing ADB Debugging.
  4. On the phone, check the status display in the Wear OS companion app for the following: 
    Host: connected
Target: connected

    5. The watch is now connected to the debugger, and you're ready to start debugging.

When you debug a watch using Bluetooth, adb always uses the IP address 127.0.0.1 plus the port that you assign. In this example, the port is 4444. All adb commands use the following format:

adb -s 127.0.0.1:4444 <command>

If you are not using the emulator and have only one device connected for debugging, you don't need to specify the address:

adb <command>

Use screen record for Wear OS

If you develop on macOS, you can use the GitHub project Android tool for Mac to record a video from your Wear OS device.

Alternatively, record a video from your Wear OS device using the following steps:

  1. Record raw frames on the watch: 
    adb shell screenrecord --time-limit 30 --output-format raw-frames --verbose /sdcard/video.raw
  2. Copy the raw file to your development machine: 
    adb pull /sdcard/video.raw video.raw
  3. Use ffmpeg to convert the raw file to MP4: 
    ffmpeg -f rawvideo -vcodec rawvideo -s 400x400 -pix_fmt rgb24 -r 10 -i video.raw -an -c:v libx264 -pix_fmt yuv420p video.mp4

    Note: Refer to the FFmpeg website for download and installation instructions.