Chime device guide for Android

The fundamental Chime device type may be implemented using either the standard Matter-based trait com.google.home.matter.standard.Chime or Google's own custom version of the trait, com.google.home.google.Chime, which, in addition to the capabilities specified in the Matter standard, supports external chimes. A chime device may also implement the Identify trait, which provides a means to identify the chime device by sight or sound.

Always check for attribute and command support for a device prior to using any features or attempting to update attributes. See Control devices on Android for more information.

Get basic information about a device

   Implemented in Sample App for Android   

The BasicInformation trait includes information like vendor name, vendor ID, product ID, product name (includes model information), and software version for a device:

// Get device basic information. All general information traits are on the RootNodeDevice type.
    device.type(RootNodeDevice).first().standardTraits.basicInformation?.let { basicInformation ->
        println("vendorName ${basicInformation.vendorName}")
        println("vendorId ${basicInformation.vendorId}")
        println("productId ${basicInformation.productId}")
        println("productName ${basicInformation.productName}")
        println("softwareVersion ${basicInformation.softwareVersion}")
    }

Multipart support

A chime may be composed of multiple device types, including a Chime and optionally a Speaker. In addition, some chimes incorporate a Thread Border Router (TBR). To ensure the broadest support, Home APIs apps that control chimes should be written to accommodate multipart chime devices. See Multipart devices for more information.

Each multipart chime device should be represented in the app by a single tile. The Chime device should be the primary device, and a child Speaker should be a part under the Chime.

Speaker volume should appear as a primary setting of a Chime device.

OnOff mapping

For a chime with both a Chime and Speaker device type, an OnOff button in a controlling app should be mapped to the Chime's Enabled attribute.

Per the Matter Device Library specification, setting the Chime trait's Enabled attribute to False may, in addition to disabling the Chime, act like a global mute switch that suppresses all audible and visual indicators.

Automation support

As stated previously, because a ChimeDevice may have multiple parts, developers are encouraged to treat all chimes as multipart devices, and this remains true in the case of automations that use chimes.

Chimes may be used in automation starters and actions.

Any component part device under the parent Chime device that's used in the automation must be referenced using an AutomationPartPath .

The following automation demonstrates how to create an automation with a multipart chime that implements the Chime trait as well as a Speaker. The automation is triggered when the front door is opened:

import com.google.home.automation.automation
import com.google.home.automation.greaterThan
import com.google.home.google.GoogleDoorDevice
import com.google.home.google.OpenClose
import com.google.home.matter.standard.ChimeDevice
import com.google.home.matter.standard.Chime
// ...

// Fetch devices
val devices = homeManager.devices()

// Fetch devices using the multipart device model.
val multipartDevices = homeManager.devices(enableMultipartDevices = true)

val doorDevice = devices.first() {
  it.has(GoogleDoorDevice) &&
  it.has(OpenClose)
}

// Obtain a reference to the chime device.
val chime = multipartDevices.first() {
  it.has(ChimeDevice) &&
  it.has(Chime)
}

// Extract the AutomationPartPath for the specific Chime part
val chimePartPath = chime.automationPart(chime.part(ChimeDevice).first())!!

// Build the automation
val chimeAutomation = automation {
  sequential {
    val doorOpenClose = stateReader<_>(doorDevice, GoogleDoorDevice, OpenClose)
    // Starter: When the door state changes
    val starterNode = starter<_>(doorDevice, GoogleDoorDevice, OpenClose)
    condition {
     expression = doorOpenClose.openPercent greaterThan(0)
    }
    // Action: Play a chime sound
    action(chimePartPath) {
      command(Chime.playChimeSound())
    }
  }
}

See Multipart device automations for additional information on automations using multipart devices.

Check connectivity for a device

Connectivity for a device is actually checked at the device type level because some devices support multiple device types. The state returned is a combination of the connectivity states for all traits on that device.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

A state of PARTIALLY_ONLINE may be observed in the case of mixed device types when there is no internet connectivity. Matter standard traits may still be online due to local routing, but cloud-based traits will be offline.

Get the IP address of the device

To find the IP address of the device, use the networkInterfaces attribute of the GeneralDiagnostics trait. The addresses are returned as byte arrays, which you can format to standard IPv4 or IPv6 strings:

val ipAddresses =
  trait.networkInterfaces?.flatMap { networkInterface ->
    (networkInterface.ipv4Addresses + networkInterface.ipv6Addresses).mapNotNull { bytes ->
      try {
        java.net.InetAddress.getByAddress(bytes).hostAddress
      } catch (e: java.net.UnknownHostException) {
        null
      }
    }
  } ?: emptyList()