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](https://developer.android.com/training/wearables/apps/creating#connect-watch-wired).


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](https://developer.android.com/training/wearables/get-started/connect-phone).

**Note:** If you don't have a physical watch, you can also
test and [run
your app on an emulator](https://developer.android.com/training/wearables/get-started/creating#run-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](https://developers.google.com/android/images-watch)
or a
[full OTA image](https://developers.google.com/android/ota-watch)
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:  

   ```bash
   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](https://developer.android.com/training/wearables/get-started/debugging#enable-dev-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](https://developer.android.com/studio/debug/dev-options#enable) 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>
```  

Refer to the following related resources:

- [Android Debug Bridge (adb)](https://developer.android.com/studio/command-line/adb)
- [Debug your app](https://developer.android.com/studio/debug)
- [Design principles](https://developer.android.com/training/wearables/design/design-principles)
- [Capture Wear UI screens](https://developer.android.com/training/wearables/get-started/screenshots)