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.
  • Supported camera and doorbell devices, including Matter-capable Google Nest cameras and doorbells as well as compatible partner cameras. For details on supported and unsupported models, see Cameras and doorbells.

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.
  • Non-camera dual-path devices (devices that implement both Matter and Cloud-to-cloud, other than supported cameras and doorbells).
  • Unsupported camera and doorbell devices, including smart displays with built-in cameras and legacy cameras that don't support Matter (see Cameras and doorbells).

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:

  • If a device provides multiple functions, such as 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 are affected.
  • Removing a camera or doorbell permanently deletes all 24/7 video history, event video history, recorded clips, and familiar face library data associated with that camera across the entire home structure.
  • Decommissioning a camera does not cancel active subscriptions, such as Google Home Premium or partner monitoring services. Subscriptions continue until cancelled by the user.
  • When decommissioning a camera or doorbell, the Home APIs platform presents a Google-managed confirmation screen to the user explaining that video history will be permanently erased. The user must confirm this prompt before the device is removed.
  • Be cautious when deleting devices on shared surfaces, because this can have unintended consequences for others.
  • Device removal must 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 when necessary. To check if a device is eligible to be removed, use the following command:

swift let eligibility = try await device.decommissionEligibility

Matter devices

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

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

swift let decommissionedDeviceIDs = try await device.decommission()

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 decommission():

swift do { let decommissionedDeviceIDs = try await device.decommission() print("The following devices were decommissioned: \(decommissionedDeviceIDs)") } catch { print("An error occurred: \(error)") }

Cameras and doorbells

You can remove supported cameras and doorbells programmatically using decommission().

Supported models include:

  • Google Nest Cam (indoor, wired)
  • Google Nest Cam (outdoor or indoor, battery)
  • Google Nest Cam with floodlight
  • Google Nest Doorbell (battery)
  • Google Nest Doorbell (wired)
  • Compatible partner cameras and doorbells (such as Walmart onn.)

The following camera and doorbell devices cannot be decommissioned programmatically:

  • Smart displays with built-in cameras, such as Google Nest Hub Max.
  • Legacy Nest cameras and doorbells that don't support Matter and connect only through cloud services, such as Nest Cam Indoor (1st gen), Nest Cam Outdoor (1st gen), Nest Cam IQ, and Nest Doorbell (wired, 1st gen).
  • Third-party Cloud-to-cloud linked cameras and doorbells.

When your app initiates decommissioning for a camera or doorbell, the platform displays a Google-managed confirmation screen to the user. This screen informs the user that removing the camera permanently deletes all recorded 24/7 video history, event history, clips, and familiar face library data associated with the device across the entire structure.

If the user dismisses or cancels the confirmation screen, decommission() throws a HomeError.

Decommissioning a camera does not cancel active camera subscriptions (such as Google Home Premium). Users must cancel subscriptions separately through the subscription provider.

swift do { let decommissionedDeviceIDs = try await device.decommission() if decommissionedDeviceIDs.contains(device.id) { // Camera was successfully decommissioned } } catch { // Handle cancellation or decommission error }

Non-Matter devices

Non-Matter devices (other than supported cameras and doorbells) cannot be removed programmatically. To remove other non-Matter devices, 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 decommission() on an unsupported non-Matter device, a HomeError is thrown.

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

swift guard try await !self.context.devices().list().contains(where: { $0.id == deviceID }) else { // The device still exists in Home APIs }