Chime device guide for iOS

The fundamental Chime device type may be implemented using either the standard Matter-based Matter.ChimeTrait or Google's own custom version of the trait, Google.ChimeTrait, which, in addition to the capabilities specified in the Matter standard, supports external chimes. A chime device may also implement the Matter.IdentifyTrait, 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 iOS for more information.

Get basic information about a device

   Implemented in Sample App for iOS   

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

let vendorName = basicInfoTrait.attributes.vendorName!
let vendorID = basicInfoTrait.attributes.vendorID!
let productID = basicInfoTrait.attributes.productID!
let productName = basicInfoTrait.attributes.productName!
let softwareVersion = basicInfoTrait.attributes.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 ChimeDeviceType 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 GoogleHomeSDK
import GoogleHomeTypes

typealias ChimeTrait = Matter.ChimeTrait
typealias OpenCloseTrait = Google.OpenCloseTrait

// Fetch devices using the multipart device model.
let multipartDevices = try await home.devices(enableMultipartDevices: true).list()

guard let chimeParentDevice = multipartDevices.first(where: {
  $0.types.contains(ChimeDeviceType.self)
}) else { return }

guard let doorDevice = multipartDevices.first(where: {
  $0.types.contains(GoogleDoorDeviceType.self)
}) else { return }

// Extract the AutomationPartPath for the specific Chime part
guard let chimeType = await chimeParentDevice.types.get(ChimeDeviceType.self),
  let chimePartPath = chimeParentDevice.automationPart(chimeType) else {
  return
}

let starterNode = starter(doorDevice, GoogleDoorDeviceType.self, OpenCloseTrait.self)

let doorOpenClose = stateReader(doorDevice, GoogleDoorDeviceType.self, OpenCloseTrait.self)

// Build the automation
let chimeAutomation = automation(
  name: "Multipart Chime Demo",
  description: "Activate the chime when the door is opened"
) {
starterNode
condition {
  starterNode.openPercent.unwrapOptional().greaterThan(0)
}
  // Action: Play a chime sound
  action(chimePartPath) {
    ChimeTrait.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.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

A state of partiallyOnline 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 GeneralDiagnosticsTrait. The addresses are returned as Data objects, which you can format to standard IPv4 or IPv6 strings using the Network framework:

func getIpAddresses(trait: Matter.GeneralDiagnosticsTrait) -> [String] {
  let interfaces = trait.attributes.networkInterfaces ?? []
  var ipAddresses: [String] = []

  for interface in interfaces {
    for data in interface.iPv4Addresses {
      if let ipv4 = IPv4Address(data) {
        ipAddresses.append(String(describing: ipv4))
      }
    }
    for data in interface.iPv6Addresses {
      if let ipv6 = IPv6Address(data) {
        ipAddresses.append(String(describing: ipv6))
      }
    }
  }

  return ipAddresses
}