Compliance Guide

About this document

This guide outlines the compliance and certification requirements for the Works with Home Assistant program. It is intended for manufacturers that wish to integrate with Home Assistant and certify their devices accordingly.

The document is split into two parts:

• Part One: General — an overview of the program, its purpose, and the requirements that apply to all partners.
• Part Two: Technical — protocol-specific requirements for each certification pathway (Matter, Zigbee, Z-Wave, ESPHome, Bluetooth, and Wi-Fi), and information on prohibited devices.

Further testing specifics are also available in our sample testing document, but please note this is not exhaustive, as testing parameters have to be flexible based on device type and behavior.

Part One: General

What is the Works with Home Assistant Program?

Home Assistant is an open source home automation platform that puts local control and privacy first, giving users full control over their data with no cloud required. As one of the Open Home Foundation's core projects, Home Assistant is powered by a global community of users and developers, all working together to ensure the platform is constantly evolving and improving. Home Assistant offers a simple, powerful, and sustainable way to automate the home.

The Works with Home Assistant program certifies that a device integrates seamlessly and reliably with Home Assistant. When users see the Works with Home Assistant badge on a product, they can trust that it will work as expected — immediately upon installation, locally, and without the need for specialist technical knowledge.

The program is run by the Open Home Foundation. The foundation champions the fundamental principles of privacy, choice, and sustainability for smart homes, and for every person who lives in one. The foundation achieves this by supporting the development of open source projects and open connectivity standards.

Program requirements

All devices entering the Works with Home Assistant program must meet the following general requirements, in addition to any protocol-specific requirements outlined in Part Two.

Safety certification

Devices must have the relevant safety certifications for the regions they are sold in and the type of device, for example, the Federal Communication Commission (FCC) or Conformité Européen (CE) marking.

Firmware updates

Firmware updates should ideally be available from within Home Assistant.

Support and maintenance

Support contact and integration maintainer — if the integration does not use an open standard such as Matter, Zigbee, or Z-Wave, the partner must be the maintainer of their integration and provide the Open Home Foundation with the contact details of the developers in charge. If the integration runs via an open standard, we require a technical contact from your team who is responsible for this.

Certification agreement

All Works with Home Assistant partners will need to agree to the terms of the certification agreement.

Testing

Two devices per product need to be sent to us for technical and support testing.

Community standards

Be a positive brand in the Home Assistant community.

Commercial fee

500 Swiss francs (CHF) annually (per partner, not per device).

Correct use of Home Assistant and Works with Home Assistant badges

The Home Assistant logo and Works with Home Assistant badge are trademarked symbols of our mission and commitment to privacy, choice, and sustainability. As a certified partner, you will be granted access to the Works with Home Assistant badge for use on your products and documentation. This signals that your product aligns with our core values and has passed certification. Correct use of the Home Assistant brand and Works with Home Assistant badge is essential to maintaining trust with our shared community.

Certified partners who intend to use the Home Assistant logo and Works with Home Assistant badge must adhere to the Open Home Foundation’s trademarks and guidelines, including the Works with Home Assistant Badge and Brand Guidelines.

If you are misusing any trademarks of the Open Home Foundation, such as the Works with Home Assistant badge, and are not adhering to our brand guidelines, we will not consider your application until the use is rectified.

Core integrations

Connecting a manufacturer’s device to Home Assistant via WiFi or Bluetooth requires an integration. While anyone can create and distribute a custom integration independently, integrations that meet a defined set of quality requirements can be built directly into Home Assistant. These are called core integrations.

Core integrations are used by the majority of the Home Assistant community. They are designed to provide a simple, reliable experience for users immediately upon installation, with no additional downloads or manual configuration required. Core integrations are built and maintained by community members, the core team, and device manufacturers who wish to support their devices within the platform.

For partners who wish to build or take ownership of a core integration, please see our Core Integration Summary. Refer to Part Two for technical requirements.

Partnership promise

If the devices meet all the program requirements the manufacturer becomes a certified partner, they will receive the following from the Open Home Foundation:

• Works with Home Assistant badge — access to the applicable trademarked Works with Home Assistant badges for use on product packaging and documentation pages.
• Dedicated integration page — an integration page noting the partnership and displaying the Works with Home Assistant logo, visible to the two million users who search these pages to find compatible devices.
• Co-marketing — we will use Home Assistant’s blog and social media accounts to announce and promote the partnership to our users.
• Quarterly updates — Open Home Foundation will discuss upcoming changes and features to the platform, the program, and more.
• Certified devices will appear on the Works with Home Assistant certified device list — a public, searchable list.

Part Two: Technical requirements

This section details the technical requirements for each certification pathway. Identify which protocol your devices use and ensure you meet the relevant requirements.

Matter

The Matter integration is available in Home Assistant and maintained by the Open Home Foundation. For the purposes of the Works with program, devices are tested against this integration.

01. Connectivity Standards Alliance certification

• Matter items must be certified by the Connectivity Standards Alliance.
• Unreleased devices will not be certified by the Works with program until the Alliance completes certification. However, if Alliance testing has already begun for a device, the Works with team can accept it for concurrent testing.

02. Vendor-specific (custom) clusters

• We only accept custom clusters/attributes for functionality that is not available in the official Matter specification, and will not be in the foreseeable future.
• If a device contains vendor-specific clusters with relevant additional configuration that can be beneficial for users (for example, only controllable by a vendor-specific app), vendors may provide the information to us so we can add parsing of these details.
• We require written documentation including the following information:
  • Cluster ID of the custom cluster
  • Attribute-IDs and their details (datatype, read/write flags, meaning, unit)
  • Command-IDs and their details (request and response data, functionality)
  • Event-IDs and their details

03. Firmware updates

• Over-the-air (OTA) firmware updates should be available to Home Assistant users from within the Home Assistant ecosystem.
• We use the Matter distributed compliance ledger (DCL), which our server pulls from daily. Use this to provide us with firmware updates.

04. General testing

• A device must be able to handle up to five concurrent controllers (multi-admin) at the same time. While assessing this capability is part of Matter certification, devices must also be checked in-house specifically with Home Assistant.

Zigbee

The Zigbee Home Automation (ZHA) integration is available in Home Assistant. There is also a popular community alternative called Zigbee2MQTT. For the purposes of the Works with program, devices are tested against ZHA. We encourage all manufacturers to ensure their devices also work well with Zigbee2MQTT, as some of our more technical users may prefer this option. ZHA uses the Zigpy Library.

01. Connectivity Standards Alliance (CSA) certification

• Zigbee devices must be certified by the Connectivity Standards Alliance.
• Unreleased devices will not be certified by the Works with program until the Alliance completes certification. However, if Alliance testing has already begun for a device, the Works with team can accept it for concurrent testing.

02. Quirks

• Most Zigbee devices have functions that work outside of the specification. The ZHA integration adheres very closely to the Zigbee specification, and therefore if a device has functions outside of this, they will need extra code to be added to our libraries. We refer to these Python scripts as ‘quirks’.
• If you do not have resources in-house to contribute to these scripts, we recommend contacting the Works with team. We can introduce you to community members, so you can engage formally with someone relevant to complete the task.
• Alternatively, manufacturers must provide written documentation detailing what each quirk should do, and any relevant values, so our team can assess if we are best placed to document these quirks in the Zigpy library.
• Writing quirks in the ZHA libraries for devices is ultimately the manufacturer’s responsibility. You will need the internal resources to submit quirks to GitHub.

03. Firmware updates

• OTA firmware updates must be available to Home Assistant users from within the Home Assistant ecosystem.
• Please refer to guidance on how to submit firmware updates via Zigpy for further information.

Z-Wave

The Z-Wave integration is available within Home Assistant and maintained by the Open Home Foundation. For the purposes of the Works with program, devices are tested against this integration. It uses the Z-Wave JS driver (zwave-js.github.io/zwave-js).

01. Z-Wave Alliance certification

• Z-Wave items must be Z-Wave Alliance certified.
• Unreleased devices will not be certified by the Works with program until the Z-Wave Alliance completes certification. However, if Z-Wave Alliance testing has already begun for a device, the Works with team can accept it for concurrent testing.

02. Device configuration files

• Configuration files improve the user experience in Home Assistant and any other projects using Z-Wave JS. They commonly include:
  • Device identification: manufacturer, label, firmware versions.
  • Associations: to improve what the device reports or to provide information the device does not report.
  • Configuration parameters.
  • Toggling device-specific workarounds for firmware bugs.
• Please refer to the guide for contributing configuration files for further information.
• Please follow the Z-Wave JS style guide when labelling UI elements.
• If you do not have resources in-house to contribute configuration files, we recommend contacting the Works with team. We can introduce you to community members, so you can engage formally with someone relevant to complete the task.
• Submitting device configuration files is ultimately the manufacturer’s responsibility and a requirement of the Works with Home Assistant program.

03. Firmware updates

• OTA firmware updates should be available to Home Assistant users from within the Home Assistant ecosystem.
• Please refer to guidance on how to submit firmware updates via Z-Wave JS for further information.

ESPHome

The ESPHome integration allows ESPHome devices to connect directly to Home Assistant with the native ESPHome API. For the purposes of the Works with program, devices are tested against this integration.

01. Federal Communications Commission (FCC) and Conformité Européenne (CE) certifications

• As is standard, all devices received for testing must have the relevant safety certification for the region in which they are being sold.
• ESPHome devices are popular with start-up companies that might not have experience with safety certifications yet. Please confirm you have the relevant certification.
• Devices must be CE certified, FCC certified, or both.

02. Made for ESPHome

• Before entering the Works with program, devices must first be accepted into the Made for ESPHome program.
• Current Made for ESPHome requirements include:
  • Devices use an ESP32 chip.
  • Manufacturers must be proactive in keeping their published configuration up to date with the latest ESPHome changes.
  • (Optional but recommended) Ideally devices have a USB port that allows users to install firmware and retrieve logs.
  • OTA requirements:
    • Must provide pre-built firmware using the update/OTA components in ESPHome.
    • Must provide the configuration source so users can take control, update locally, and make modifications themselves.
  • Improv requirements:
    • Improv Serial is configured (if USB port accessible).
    • Improv via BLE (Bluetooth Low Energy) is configured. It is recommended that Improv via BLE uses user presence via the authorizer configuration.

03. Web flashers

• Web flashing using ESP Web Tools deployed to a public website (for example, GitHub) allows users to install firmware to a device when it is not updating via OTA, or when the user has previously flashed their own custom firmware, and wants to revert back to the manufacturer’s standard firmware.

04. Filtering sensors

• An ESPHome device’s configuration can technically support many sensors, but only a small subset of this data is typically relevant to most users.
• Sensors/entities should use relevant filters to limit the frequency of data being transferred into Home Assistant to what’s necessary.
• Any sensors that do not provide primary information most users would want on their dashboard should be marked with the entity category ‘diagnostic’.

Bluetooth

A Bluetooth certificate is issued when the certified partner proves that:

• The device is certified by the Bluetooth Special Interest Group (Bluetooth SIG); and
• It meets the requirements for the issuance of a local certificate:
  • The Home Assistant integration reaches Gold tier or above on the integration quality scale (see below)
  • The partner actively maintains the core integration (themselves or via a third party), with named developer contacts provided
  • Any libraries used in the integration are published under an OSI-approved open source license

A Bluetooth device must meet the following integration quality requirements:

Integration quality

• Integration must be set up via the user interface — users do not enter manual YAML code.
• Integration uses account linking for OAuth — users do not enter passwords or keys directly.
• Integration has auto-discovery, if possible — users will see their devices automatically and can initiate setup immediately.
• An integration quality scale level of Gold or above is required.

Wi-Fi

Integration quality

• Wi-Fi device supports 2.4 GHz as standard.
• Integration must be set up via the user interface — users do not enter manual YAML code.
• Integration uses account linking for OAuth — users do not enter passwords or keys directly.
• Integration has auto-discovery, if possible — users will see their devices automatically and can initiate setup immediately.
• An integration quality scale level of Gold or above is required.

Prohibited devices

The following categories of devices are not eligible for Works with Home Assistant certification. If you are unsure whether a product falls into one of these categories, please contact us before submitting.

Cloud-dependent devices

• Devices that do not work locally.
• Devices that have a cloud dependency — i.e. the device operates locally but only after Matter or another protocol is enabled through a cloud app or similar service.

Connecting devices

Definition

A connecting device — such as a bridge, hub, stick, repeater, antenna, coordinator, or proxy — is a product whose primary function is to connect other devices to a network or protocol, rather than perform a discrete function of its own for the end user. Examples include:

• Devices that join Zigbee, Z-Wave, or Bluetooth, DALI or KNX devices to Wi-Fi, Ethernet, Matter, or Home Assistant in another way
• Devices that act as a Thread border router
• Multi-protocol coordinators that also run local automation, since bridging is still their primary function

Eligibility

A standalone consumer device (for example a speaker, sensor, or lock) doesn’t lose eligibility just for having a secondary connecting capability — eligibility follows the primary advertised functions.

Devices not available to the general public

• Devices that are not available to purchase by the general public — i.e. only available via an installer.
• Devices that are not intended for the general homeowner — i.e. products that are too installer-focused or complex for a regular user.

Remote controls

• Remote controls are not eligible for certification.
• Note: The distinction between a remote control and a collection of switches (such as a wall panel) is an area of ongoing discussion.
• Wall panels running Android or similar operating systems: eligibility will be assessed on a case-by-case basis depending on whether they meet Works with Home Assistant program requirements.

Screens and displays

• Screens, tablets, e-ink devices and displays for use as a Home Assistant dashboard are not eligible for certification.
• Exceptions include very small screens that are not intended for use as a dashboard, for example a small temperature sensor or air quality monitor that has a screen to show the temperature.

Community-built integrations

• Devices that use a community-built integration that the manufacturer is not responsible for are not eligible for certification. This does not apply to integrations for open protocols, such as Zigbee, Z-Wave, or Matter, which are managed by the Open Home Foundation. Examples of ineligible integrations include WLED, Modbus, and MQTT (see MQTT section below).

MQTT

• If a device relies on Home Assistant’s MQTT integration, it generally does not qualify as “working immediately upon installation,” since the user must first set up and configure a broker — separate software that routes messages between devices and Home Assistant — before the device can connect.
• Because the MQTT integration is community-contributed, we do not promote or certify individual manufacturer implementations that depend on it, as they do not fulfill the contractual obligation of maintaining your own integration. We cannot guarantee that the community-contributed integrations will always function as expected or stay maintained.

Alternative paths to certification

ESPHome

If your device is built on a supported microcontroller chip, ESPHome may offer a simpler path to certification. Rather than relying on MQTT, ESPHome uses its native API to communicate directly with Home Assistant. This provides a more powerful and seamless connection that does not require a broker or complex setup.

Core integration

Alternatively, manufacturers who wish to apply to the Works with Home Assistant program will need to build a dedicated core integration with an embedded broker functionality. This will allow the integration to connect to the broker automatically, for a smoother experience for the end user. See the Core Integrations section in Part One for further guidance.

Credential-required setup

• Any device that requires a user credential on a vendor’s external app, for example to enable a key feature or complete setup, is not eligible for certification.
• Examples include: Matter commissioning via a cloud app, lock calibration via a vendor app, etc.

Items that have missing features in Home Assistant

Works with Home Assistant certification requires that a device’s primary functions work reliably and locally in Home Assistant. Certification will not be granted if the primary functions do not work, regardless of how well secondary features perform. It will also not be granted if our team has no capability to test these functions, or if the function is one of a bridge/hub.

Differentiating primary functions from secondary functions

Primary functions: the core purpose of the device — the reason a user buys it. This includes any capability prominently advertised, named in the product title, shown on primary packaging/imagery, or reasonably expected based on the product category (for example, a lock must lock; a power plug must support on/off control and any advertised energy monitoring).

Secondary functions: additional features that support but aren’t essential to the device’s core purpose (for example, a night light on a sensor, signal repeating, a physical button that isn’t necessary for core operation).

To determine whether a feature represents a primary or secondary function, ask:

• Is it one of the main marketed features?
• Is it in the device name or shown prominently on the device/packaging?
• Is it a reason people specifically buy this product?
• Would a reasonable user feel misled if it didn’t work?

If the answer to any of these is yes, treat the feature as a primary function. That means certification will not proceed if the feature is missing or not testable from Home Assistant, even if it is functional elsewhere.

If a device’s secondary features do not work with Home Assistant, the device may still qualify for certification provided:

1. The secondary feature that does not work with Home Assistant is disclosed on the device’s Home Assistant integration page, and, where relevant, the badge/certified device page.
2. The tester confirms whether the lack of functionality with Home Assistant is due to a connectivity/protocol limitation (for example, a feature not yet supported by Matter), or a lack of vendor integration effort. This affects both the disclosure wording and improvement roadmap.