HomeDevice

interface HomeDevice : HasId, HasTraits, HasDeviceTypes, HasConnectivityState, HasCandidates, HasCustomAppData, HasGenericTypes

A device supporting traits, commands, and subscriptions.

Summary

Public functions
AutomationPartPath?

Returns a new AutomationPartPath with the given DeviceType added to the path.
suspend DecommissionEligibility

Checks if the device is eligible for decommissioning.
suspend Set<Id>

Initiates the decommissioning of this device.
suspend Set<Id>

Initiates the device decommissioning process with consent.
suspend Room?

Gets the up-to-date Room this device is a part of.
suspend HomeDevice
setName(newName: String)

Sets the user-given name of this device.
suspend Structure?

Gets the up-to-date Structure this device is a part of.

Public properties
Boolean

If this device is backed by Matter.
String

The user-given name of this device.
Id?

The ID of the Room this device is a part of.
Id?

The ID of the Structure this device is a part of.
Map<DeviceTypeFactory<DeviceType>, List<Set<Tag>>>

The tags on parts of this device.

Extension functions
suspend Unit

Extension function to delete the history items for a device.
suspend HistoryItemsPage

Inherited functions
From com.google.home.automation.HasCandidates
Flow<Set<NodeCandidate>>

Returns all the automation NodeCandidate instances for the receiver and its child objects.
Flow<Set<NodeCandidate>>

Returns all the automation NodeCandidate instances for the receiver.
From com.google.home.HasCustomAppData
suspend Unit

Deletes the value associated with the given key.
suspend String?

Retrieves the value associated with the given key.
suspend Unit
updateValue(key: String, value: String)

Updates the value associated with the given key.
From com.google.home.HasDeviceTypes
Boolean
<T : DeviceType> has(type: DeviceTypeFactory<T>)

Checks if a device type is supported by this device.
open Flow<T>
@HomeExperimentalApi
<T : DeviceType> part(type: DeviceTypeFactory<T>, vararg tags: Tag)

Gets a flow on the DeviceType using the given DeviceTypeFactory and Tag.
open Flow<T?>
@HomeExperimentalApi
<T : DeviceType> partOrNull(type: DeviceTypeFactory<T>, vararg tags: Tag)

Gets a flow on the DeviceType using the given DeviceTypeFactory and Tag.
open Flow<Set<DeviceType>>

Gets a flow on the DeviceTypes that are parts of this HomeDevice.
Flow<T>
<T : DeviceType> type(type: DeviceTypeFactory<T>, vararg tags: Tag)

Gets a flow on the DeviceType using the given DeviceTypeFactory.
Flow<T?>
<T : DeviceType> typeOrNull(type: DeviceTypeFactory<T>, vararg tags: Tag)

Gets a flow on the DeviceType using the given DeviceTypeFactory.
Flow<Set<DeviceType>>

Gets a list of all available types on the HomeDevice.
From com.google.home.HasGenericTypes
Flow<Set<GenericDeviceType>>
From com.google.home.HasTraits
SourceConnectivity?

Gets metadata, such as network locality and connectivity state, about the source of data for a particular trait.
Boolean
<T : Trait> has(trait: TraitFactory<T>)

Checks if a trait is supported by a device.

Inherited properties
From com.google.home.HasConnectivityState
SourceConnectivity

Source Connectivity for the device.
From com.google.home.HasId
Id

Opaque ID for the object.

Public functions

automationPart

@HomeExperimentalApi
fun automationPart(deviceType: DeviceType): AutomationPartPath?

Returns a new AutomationPartPath with the given DeviceType added to the path.

Parameters
deviceType: DeviceType

the DeviceType to add to the path.
Returns
AutomationPartPath?

a new AutomationPartPath with the given DeviceType added to the path, or null if the device type is not found in the path.

checkDecommissionEligibility

suspend fun checkDecommissionEligibility(): DecommissionEligibility

Checks if the device is eligible for decommissioning.

Returns
DecommissionEligibility

a data class representing the device's eligibility for decommissioning.

decommissionDevice

suspend fun decommissionDevice(): Set<Id>

Initiates the decommissioning of this device. Throws an exception if the device is not eligible for decommissioning.

If the device requires consent for decommissioning (e.g. some cameras), this method will automatically initiate the consent flow and retry if consent is granted.

Returns
Set<Id>

the set of device IDs that were affected by the decommissioning of this device.

initiateDecommissioningWithConsent

@HomeExperimentalApi
suspend fun initiateDecommissioningWithConsent(): Set<Id>

Initiates the device decommissioning process with consent. Opens a Google-hosted consent WebView and calls standard Matter decommission trait.

Returns
Set<Id>

the set of device IDs that were affected by the decommissioning.
Throws
HomeException

if the device is not eligible for decommissioning or the decommissioning process fails due to other reasons such as invalid/missing consent token.

room

suspend fun room(): Room?

Gets the up-to-date Room this device is a part of.

Returns
Room?

the Room this device is a part of, or null if the device is not in a Room.

setName

suspend fun setName(newName: String): HomeDevice

Sets the user-given name of this device.

Parameters
newName: String

the new name for this device.
Returns
HomeDevice

an updated HomeDevice, with the new name, or previous name if the update failed.
Throws
HomeException

if the update failed.
CancellationException

if the update is cancelled.

structure

suspend fun structure(): Structure?

Gets the up-to-date Structure this device is a part of.

Returns
Structure?

the Structure this device is a part of, or null if the device is not in a Structure.

Public properties

isMatterDevice

val isMatterDevice: Boolean

If this device is backed by Matter.

name

val name: String

The user-given name of this device.

roomId

val roomId: Id?

The ID of the Room this device is a part of. Null if the device is not in a Room.

structureId

val structureId: Id?

The ID of the Structure this device is a part of. Null if the device is not in a Structure.

tags

@HomeExperimentalApi
val tags: Map<DeviceTypeFactory<DeviceType>, List<Set<Tag>>>

The tags on parts of this device. A device can have multiple parts with same type but different tags. This allows us to identify the part by tags. Key is the DeviceTypeFactory of the part, and the value is a list of PartTags which can be used to uniquely identify a part.

Extension functions

deleteHistory

@HomeExperimentalApi
suspend fun HomeDevice.deleteHistory(): Unit

Extension function to delete the history items for a device.

getHistoryItems

@HomeExperimentalApi
suspend fun HomeDevice.getHistoryItems(pageSize: Int = 20): HistoryItemsPage