Matter

Matter is a smart-home communication protocol. It is build upon Wi-Fi, Ethernet and Thread. It is only available on Homey Pro (Early 2023).

Matter apps are supported since Homey Pro (Early 2023) v11.1.0.

Matter is a smart-home protocol that was released by the Connectivity Standards Alliance in 2022. The standard describes how the Matter protocol functions and how devices using Matter should react to certain commands. Because of this, Homey Pro can control all Matter devices without the need of a Homey App. However, Homey apps can enhance the experience of a Matter device by adding pairing instructions and device icons.

Creating a Matter Driver

To create a matter driver you'll need to add a driver manifest file in /drivers/<driver_id>/driver.compose.json. This file will describe your Matter device. You will need to add at least the following fields in this file (also add the required fields described in Driver Manifest on the Drivers & Devices page).

• platforms: Always specify "local" here. Matter is not available on Homey Cloud.

• connectivity: Always specify "matter" here. This is what makes your driver a driver for a Matter device.

• class: Use a device class that best fits your device.

• capabilities: Set the capabilities your device has (you can find the capabilities in the developer tools after you have added your device to Homey Pro).

• matter: An object that describes some specific properties for Matter.

  • vendorId: The vendor id that the Matter device uses (number or number array to support multiple devices with a single driver).

  • productId: The product id that the Matter device uses (number or number array to support multiple devices with a single driver).

Note that the class and capabilities fields are only used to display the Matter device in the Homey App Store. When a Matter device is added to Homey Pro it will automatically determine which capabilities and device class are suited for it, and the capabilities and device class of the driver manifest are ignored.

You can find the vendor id and product id of a Matter device by checking the advanced settings of the device after adding it to Homey. Note that the advanced settings show a vendor and product id in hexadecimal (e.g. 0x1234), but you can only put a base-10 number in your driver.compose.json (e.g. 4660).

Driver and Device

Because it is only possible to provide icons and pair instructions for a Matter device you cannot provide a custom Driver or Device class for the device. Homey Pro will take care of handling all capabilities and device updates.

Adding Pair Instructions

To make it easier for a user to connect a Matter device to Homey Pro, you can add pairing instructions to your driver. These instructions should tell the user how to put the Matter device into pairing mode. To add pairing instructions, add a field learnmode to the matter field of your driver.compose.json. It has the following fields:

• instruction: A translation object that tells how to enable the pairing mode on the device.

• image: An image (or animated SVG) that shows how to enable the pairing mode on the device (optional).

Adding An Icon

Refer to Drivers & Devices on how to add an icon to your driver.

Example Manifest

Below you see an example driver.compose.json file for a Matter device.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "platforms": ["local"],
  "connectivity": ["matter"], 
  "class": "socket",
  "capabilities": ["onoff", "dim"],
  "matter": {
    "vendorId": 1234,
    "productId": 4567,
    "learnmode": {
      "instruction": { "en": "Press the button on your device three times" },
      "image": "/drivers/<driver_id>/assets/learnmode.svg"
    }
  }
}

Bridged Devices

The Matter specification also defines a Matter bridge. This is a device that exposes other non-Matter devices through the Matter protocol. It is possible to create a driver for a bridged Matter device.

For example: a manufacturer of a Zigbee hub can add support for Matter to its hub. The hub can then expose all Zigbee devices through the Matter protocol. The hub will convert the commands that are send through Matter to commands that can be send over Zigbee to the Zigbee devices.

To add a driver for a Matter bridge to your Homey App, you will need at least two drivers:

• A driver for the bridge itself. This driver can be selected by the user and should provide instructions on how to put the Matter bridge into pairing mode. The bridge itself will never be added as a device to Homey.

• Drivers for the bridged devices. Each driver can provide an icon for the bridged device.

Matter Bridge Manifest

The manifest for the Matter Bridge should contain the vendor id and product id of the Matter bridge itself. It should not contain any capabilities and the device class should be "other". The Matter bridge is the only device that can be selected by the user when adding a Matter device.

Example Matter Bridge Manifest

/drivers/<bridge_driver_id>/driver.compose.json

{
  "name": { "en": "My Bridge Driver" },
  "platforms": ["local"],
  "connectivity": ["matter"], 
  "class": "other",
  "capabilities": [],
  "matter": {
    "vendorId": 1234,
    "productId": 4567,
    "learnmode": {
      "instruction": { "en": "Press the button on your device three times" },
      "image": "/drivers/<bridge_driver_id>/assets/learnmode.svg"
    }
  }
}

Bridged Device Manifest

For each bridged device you should add an additional driver. This driver is used to determine the icon of the device. The manifest of a bridged Matter device should contain two additional properties in the matter object.

• deviceVendorId: The vendor id that is reported by the bridged Matter device (number or number array to support multiple devices with a single driver).

• deviceProductName: The product name that is reported by the bridged Matter device (string or string array to support multiple devices with a single driver).

You will also need to keep the vendorId and productId of the Matter bridge in the manifest. This tells Homey to which Matter bridge this device belongs.

Example Bridged Device Manifest

/drivers/<bridged_device_driver_id>/driver.compose.json

{
  "name": { "en": "My Bridged Device Driver" },
  "platforms": ["local"],
  "connectivity": ["matter"], 
  "class": "other",
  "capabilities": [],
  "matter": {
    "vendorId": 1234,
    "productId": 4567,
    "deviceVendorId": 1234,
    "deviceProductName": "XYZ-123"
  }
}

Platform Local Required Feature

You could add matter to the platformLocalRequiredFeatures array of your app manifest (refer to Platform Local Required Features). This will make it impossible to install the app on a Homey Pro that does not have support for Matter.

Adding Matter to the platformLocalRequiredFeatures array is recommended when your app only contains drivers for Matter devices. If your app has drivers for other technologies or other features, Matter should not be added to the required features list.