Remove a device

Removing a device involves decommissioning it from the structure. A user can do this using the Google Home app (GHA), and an app can programmatically decommission a smart home device. There are limitations as to which devices can be removed. Also, removing a device can affect your structure and user experiences for your app.

What you can remove

You can programmatically remove the following devices through the Home APIs:

  • Matter devices for which your app has permissions.
  • Matter bridges, provided your app has access to all the devices connected through the bridge. Removing the bridge removes all Matter devices connected to it.

What you cannot remove

The following devices can't be removed programmatically through the Home APIs:

  • Matter devices for which your app lacks user permissions.
  • Individual devices connected behind a Matter bridge.
  • Cloud-to-cloud linked devices.
  • Dual-path devices (devices that implement both Matter and Cloud-to-cloud).

Important considerations before removing a device

When your app removes a device, it is removed from the entire structure, affecting all users and all apps, including the GHA. Depending on what type of device it is, there may be additional side effects of decommissioning a device:

  • Devices implementing multiple device types: If a device has multiple functions - for example, a smart light that also acts as a hub, removing it also removes all associated devices. The app should inform the user if multiple device functions will be affected.
  • Device History: Deleting a device may result in the removal of the device's history.
  • Shared Surfaces: Be cautious when deleting devices on shared surfaces, because this can have unintended consequences for others.
  • Authentication: Device removal should only be performed on authenticated surfaces, such as a mobile phone, not on unauthenticated devices like TVs. Doing so violates the Google Home Developer Policies.

Remove a device

Checking a device's eligibility to be removed is costly and should only be done if necessary. To check if a device is eligible to be removed, use the following command:

val eligibility = device.checkDecommissionEligibility()

if (eligibility is DecommissionEligibility.Ineligible) {
  println("The device cannot be decommissioned.")
} else if (eligibility is DecommissionEligibility.EligibleWithSideEffects) {
  println("The device can be decommissioned but there will be side effects on other devices.")
} else if (eligibility is DecommissionEligibility.Eligible) {
  println("The device can be decommissioned.")
}

Matter devices

You can remove a Matter device programmatically if the device isn't behind a Matter bridge.

To remove a Matter device, call decommissionDevice() on it:

val decommissionedDeviceIds = device.decommissionDevice()

If the call doesn't throw an error, it succeeded.

You may check to see if the device's ID is among those returned by the decommissionDevice() :

if (decommissionedDeviceIds.contains(deviceId)) {
  println("Decommission successful!")
} else {
  println("Decommission failed!")
}

Non-Matter devices

Non-Matter devices cannot be removed programmatically. To remove a non-Matter device, you can issue a Sync request (see Request Sync), or delete the Cloud-to-cloud integration (see Delete a launched Cloud-to-cloud integration).

If you call decommissionDevice() on a non-Matter device, a HomeException is thrown.

Once you remove a non-Matter device, check for the presence of the device to verify it was successfully removed:

var removedDevice: HomeDevice? = null
runBlockingCustom {
  try {
    removedDevice = homeManager.devices().get(deviceId)
  } catch (exception: Exception) {
    println("removal successful!")
  }
}
if (removedDevice != null) {
  println("removal failed!")
}