Debug a Wear OS app

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 via USB.

Enable developer options on your watch

Before you can debug on your watch you must 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 will appear confirming that you are now a developer.

Debug over Wi-Fi

Before you begin, enable developer options on the watch.

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 will display the watch's IP address (for example 192.168.1.100). You'll 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. For example, if the IP address is 192.168.1.100, the adb connect command and its response will look like this (a port number, 5555 is added to the address):

    adb connect 192.168.1.100:5555
    connected to 192.168.1.100:5555
    

The watch is now connected to the debugger and you're ready to start debugging. Send adb commands to the watch using the `-s` flag and specify the watch's IP address, including 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 at all:

adb <command>

Debug over Bluetooth

Bluetooth debugging works only for Android-paired watches. Before you begin, pair the watch and phone and enable developer options on the watch. Check that developer options are enabled on the phone. To check, open the phone's Settings menu, select About phone and click the build number seven times.

Enable USB debugging on the phone

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

Enable ADB/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 down to Advanced Settings and tap to view the Advanced Settings options.
  3. Enable Debugging over Bluetooth. A status message appears under the option. It looks like this:
    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 will only be enabled with the device selected on the main screen.

Connect the debugger to the watch

In this final step, you'll 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. Use the same port in both commands. (In this example the port is 4444.)

  3. After you type the connect command, look at the watch. It will ask you to confirm that you are allowing ADB Debugging.
  4. On the phone, check the status display in the Wear OS companion app. It should look like this:
    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 alway uses the IP address 127.0.0.1 plus the port that you assigned. 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 at all:

adb <command>

Use screen record for Wear OS

If you develop on macOS®, you can use a 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.