Setting up Home Assistant with Matter Plugin on NAVQ Plus


This application note provides instructions on how to set up Home Assistant and the Matter plugin on NAVQ Plus. It also covers the process of connecting a Matter device to the Home Assistant platform.

Home Assistant

Home Assistant is an open-source home automation platform that allows you to control and automate various smart devices and services within your home. It provides a unified interface to interact with devices from different brands and protocols, enabling seamless integration and automation.

Home Assistant supports a wide range of devices, including lights, thermostats, cameras, sensors, and more. Home Assistant also offers a user-friendly web-based interface and mobile apps for convenient control and management of your smart home.

With Home Assistant, you can create custom automations, set up schedules, and create complex routines to control your devices based on different triggers and conditions. It also integrates with popular voice assistants like Amazon Alexa and Google Assistant, allowing you to control your smart home using voice commands.

Home Assistant has a large and active community of users and developers who contribute to its continuous improvement. It offers extensive customization options, flexibility, and compatibility with a wide range of smart home devices, making it a popular choice for DIY smart home enthusiasts.

With Home Assistant, you can integrate all your smart devices into a single unified platform. You can connect and integrate Matter, Thread, and Zigbee devices. This application note provides guidance on connecting Matter devices using both Bluetooth Low Energy (BLE) and Wi-Fi protocols. To connect to a Zigbee network, you will need a Zigbee adapter. For detailed instructions on Zigbee connectivity, please refer to the Zigbee Adapter section of the Using Zigbee on NAVQ Plus application note.

Similarly, to connect to a Thread network, you will need a Thread adapter. For specifics on setting up a Thread radio co-processor, please consult the Thread Radio Co-Processor section of the Setting up OpenThread Border Router on NAVQ Plus application note.

Matter Protocol

The Matter protocol, formerly known as Project CHIP (Connected Home over IP), is an open-source smart home connectivity standard developed by the Connectivity Standards Alliance (CSA). It aims to create a unified and secure standard for smart home devices, allowing them to seamlessly communicate with each other and integrate into different ecosystems.

Matter protocol is designed to address the interoperability challenges faced by consumers, device manufacturers, and smart home platforms. By adopting a common networking protocol, Matter enables devices from different brands to work together, regardless of their underlying technology or communication method. This simplifies the setup process, enhances device compatibility, and provides a more cohesive and user-friendly smart home experience.

Matter protocol is built upon existing IP-based technologies, such as Ethernet, Wi-Fi, and Thread, and leverages standard internet protocols like IPv6 and TCP/UDP. It aims to provide reliable and secure connectivity while ensuring data privacy and minimizing latency.

With the support of major industry players, including Apple, Google, Amazon, and other members of the CSA, the Matter protocol is expected to become a widely adopted standard, driving the growth and development of the smart home industry.


This application note provides instructions on running Home Assistant and Matter Server within Docker containers.

Docker is an open-source platform that enables developers to automate the deployment and management of applications within isolated, lightweight containers. It provides a way to package software and its dependencies into a standardized unit called a container. These containers provide a consistent and portable environment that can run on any system, regardless of its underlying infrastructure.


Before proceeding with the setup, ensure that you have the following:

  • NAVQ Plus #1: This will serve as the Matter device.

  • NAVQ Plus #2: This will serve as the Home Assistant server.

Software Setup

To enable a user to use Docker, execute the following command:

user@imx8mpnavq:~$ sudo usermod -aG docker user

This command adds the specified user to the "docker" group, allowing them to run Docker commands without requiring root privileges. After executing the command, you will need to log out and log back in for the changes to take effect.

To create a directory structure for container configuration files, use the following commands:

user@imx8mpnavq:~$ mkdir docker user@imx8mpnavq:~$ mkdir -p docker/homeassistant/config user@imx8mpnavq:~$ mkdir -p docker/matter-server/data

The resulting directory structure will look like this:

└── docker ├── homeassistant │   └── config └── matter-server └── data

This directory tree allows you to organize your Docker configurations for both Home Assistant and the Matter server effectively.

Switch directory to docker/homeassistant and create docker-compose configuration file compose.yaml:

user@imx8mpnavq:~$ cd docker/homeassistant user@imx8mpnavq:~/docker/homeassistant$ vim compose.yaml

Modify the file contents as follows:

version: '3' services: homeassistant: container_name: homeassistant image: "" volumes: - /home/user/docker/homeassistant/config:/config - /etc/localtime:/etc/localtime:ro restart: unless-stopped privileged: true network_mode: host

Switch directory to docker/matter-server and create a docker-compose configuration file compose.yamlfor Matter Server:

user@imx8mpnavq:~$ cd docker/matter-server user@imx8mpnavq:~/docker/matter-server$ vim compose.yaml

Modify the file contents as follows:

version: "3.8" services: # python-matter-server matter-server: image: container_name: matter-server restart: unless-stopped # Required for mDNS to work correctly network_mode: host security_opt: # Needed for Bluetooth via dbus - apparmor:unconfined volumes: # Create an .env file that sets the USERDIR environment variable. - /home/user/docker/matter-server/data:/data/ - /run/dbus:/run/dbus:ro

Resulting directory tree will look like:

└── docker ├── homeassistant │   ├── compose.yaml │   └── config └── matter-server ├── compose.yaml └── data

Start docker-compose for Home Assistant:

user@imx8mpnavq:~$ cd docker/homeassistant user@imx8mpnavq:~/docker/homeassistant$ docker-compose up -d

Start docker-compose for Matter Server:

user@imx8mpnavq:~$ cd docker/matter-server user@imx8mpnavq:~/docker/matter-server$ docker-compose up -d

To verify that the containers have started, use the docker ps command. Command output should look like the following:

user@imx8mpnavq:~/docker/homeassistant$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES cfbc0752b992 "/init" 25 hours ago Up About an hour homeassistant d87544b232cb "matter-server --sto…" 25 hours ago Up About an hour matter-server

Setting up Home Assistant

To configure Home Assistant, open your browser and enter your NAVQ Plus IP address followed by port 8123. For example,

Home Assistant Welcome Page

Proceed with the configuration steps in Home Assistant to create your smart home, including user creation and setting up your home location.

Installing Matter Plugin

When the setup is complete, let's proceed to install the Matter plugin. Click the button below to add the Matter integration plugin:

You will be prompted to open your Home Assistant:

Adding Matter integration plugin

Click on the Open Link button. You will be prompted with a message asking, Do you want to set up Matter (BETA)?Click OK.

You will be asked to provide the location information for your Matter server:

Matter Server Location Prompt

Click on Submit to finalize setting up of the Matter integration plugin. After completing the process, you will receive a notification confirming the successful creation of the Matter configuration.

Home Assistant Companion

You need to use the Home Assistant Companion app on your mobile phone to commission Matter devices.

The Home Assistant Companion app is a mobile application designed to work in conjunction with the Home Assistant platform. It is available for both iOS and Android devices.

The Companion app serves as a convenient tool for controlling and monitoring your smart home from your smartphone or tablet. It allows you to access and interact with your Home Assistant installation remotely, providing a seamless and user-friendly interface.

Please refer to this page for installation instructions for Home Assistant:

Connect Home Assistant Companion app to your Home Assistant.

Starting Matter Device

Please refer to the Running Matter Device on NAVQ Plus application note for information on how to start the Demo Matter Device that controls the Status LED on NAVQ Plus. Additionally, it will provide instructions on how to obtain the QR code required for the next step.

Adding Matter Device Using QR Code

In the Home Assistant Companion app, go to Settings → Devices & Services. Tap on the Add Integration button and select Add Matter device from the list:

Adding Matter Device to Home Assistant

When you run Matter Device Python script, the program output will include a link to a QR code for connecting your device via Matter. The link will be in the following format:

Open the QR code in your web browser.

Scan the QR code within the app and proceed with connecting your device to Home Assistant.

Once connected, Home Assistant Companion will display device information:

Device Information in Home Assistant Mobile app


Return to your Home Assistant web interface. You will find our Test Product listed under Devices.

TEST_PRODUCT in Home Assistant Web Interface

You can now click on the slider in the Controls section for TEST_PRODUCT, and it will turn on (or off) the Status LED on NAVQ Plus.

Additionally, the Logbook will display recent device activity:

Logbook Shows Recent Device Activity