Debug a Wear OS app

Stay organized with collections Save and categorize content based on your preferences.

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

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.
  3. Scroll to Build number and tap the build number seven times.
  4. A dialog 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.

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.