Matter Binding

Add-ons Bindings
,
199

Thanks a lot for sharing this setup! By following your instructions, I managed to pair Aqara U200 lite to OH.

I have to admit, process was not that easy and I’ve spent 3 evening to figure out all the bits and pieces. There were 2 major things that were not mentioned which were causing me a lot of problems:

  • Missing mention of mDNS setup requirement - I have OpenWRT router and maybe it is a standard on consumer hardware - in any case, due to that, I had a lot problems
  • 11 digit code contains only short discriminator, only QR code has long discriminator which can be used in the pairing process

I had also bit of unique problems like:

  • ESP RCP firmware having problems with compiling

  • Certificates not working at all - I’ve used --bypass-attestation-verifier true in the end

  • IPv6 not working on Raspberry Pi - no idea what caused it, did setup from Matter binding readme and it was still not working

  • When doing pairing of Aqara lock in controller, nothing appeared in the inbox. I then tried to use Scan option with pincode and this was working. I had to delete Controller, repeat the pairing process from chip-tool to OpenHab and then try to pair the lock via Scan option. As a side note, I was using Trace logging - not sure if it could affect the result somehow

    Here are some notes that I wrote for myself

1. Prerequisites

Hardware:

  • ESP32-H2: To be used as a Radio Co-Processor (RCP).

  • ESP32-C6: To host the OpenThread Border Router (OTBR).

  • Raspberry Pi: To run OpenHAB and the chip-tool.

  • Aqara U200 lite: The Thread-enabled smart lock.

Software:

  • ESP-IDF (v5.5 branch recommended): The development framework for ESP32.

  • ESP Thread BR Firmware: For the ESP32-C6.

  • RCP Firmware: For the ESP32-H2.

  • chip-tool: Installed on the Raspberry Pi ( I followed this path)

    sudo apt install snapd 

    sudo snap install chip-tool

  • OpenHAB: With the Matter binding enabled.

  • Bluetooth and IPv6: Must be available and correctly configured on the Raspberry Pi.

Setup Terminals:

  • Keep a terminal open for the OTBR console (serial monitor).

  • Keep a terminal open on the Raspberry Pi for chip-tool commands.

  • Have the Aqara U200 lite nearby to activate its pairing mode.

2. Network and Border Router Setup

This section covers flashing the ESP32 devices and establishing the Thread network.

  • On your Development Machine:

    1. Build and Flash RCP Firmware: Compile the RCP firmware for the ESP32-H2 and flash the device.

      • Note: You might encounter compile errors. A potential fix involves manually adding the following lines to esp_ot_config.h:

            #define OPENTHREAD_SPINEL_CONFIG_COMPATIBILITY_ERROR_CALLBACK_ENABLE
#define OPENTHREAD_SPINEL_CONFIG_COPROCESSOR_RESET_FAILURE_CALLBACK_ENABLE

    2. Connect Devices: Connect the flashed ESP32-H2 to the ESP32-C6 via UART. See setup on https://github.com/espressif/esp-idf/tree/v5.5/examples/openthread/ot_br

    3. Configure OTBR Firmware: Before building, run idf.py menuconfig and set the following to ensure the border router starts automatically with your network credentials:

      • Enable OpenThread Border Router Example → Enable the automatic start mode in Thread Border Router.

      • Configure Example Connection Configuration → connect using WiFi interface and fill in your Wi-Fi SSID and password.

    4. Build and Flash OTBR Firmware: Build and flash the configured ESP Thread BR firmware to the ESP32-C6.

  • On the OTBR CLI (Serial Monitor):

    1. Confirm Network Connectivity: Ensure the ESP32-C6 OTBR has an IPv6 address on your LAN. You can verify this by pinging its IPv6 address from another machine on the same network.

    2. Get the Operational Dataset: Run the following command to retrieve the active Thread network credentials:

          dataset active -x

    3. Copy the Dataset: A long hexadecimal string will be returned. Copy this string for the pairing process.

3. Prepare Commissioning Tools on the Raspberry Pi

  • Install chip-tool: If not already installed, follow the prerequisite steps.

  • Ensure mDNS is Working: The chip-tool relies on mDNS for device discovery. Install Avahi if it’s missing:

        sudo apt-get install avahi-utils
    • Troubleshooting: Initial pairing timeouts (CHIP Error 0x00000032: Timeout) often point to a missing mDNS service.

  • Obtain the Device Setup Code: Get the Matter QR code or the 11-digit manual code from your Aqara U200 lite.

  • Decode the Setup Payload: Use chip-tool to extract the pairing PIN and discriminator.

        chip-tool payload parse-setup-payload <QR_OR_11_DIGIT_CODE>
    • Note on Discriminator: The 11-digit manual code may only provide a “short” discriminator, which is not sufficient. The “long” discriminator is required and can be reliably obtained from the QR code.

4. Pair the Aqara U200 Lite to the First Fabric (chip-tool)

This step connects the lock to the Thread network managed by your ESP32 border router.

  • On the Aqara U200 lite:

    1. Enter Pairing Mode: Press the “Set” button. The device will indicate it’s in pairing mode with a blinking white light.

  • On the Raspberry Pi:

    1. Run the BLE-Thread Commissioning Command: Execute the following, replacing the placeholders. Choose a unique node-id (e.g., 100).
        chip-tool pairing ble-thread <NODE_ID> hex:<DATASET_HEX> <PIN> <DISCRIMINATOR>

    • <NODE_ID>: A unique ID for the device on this fabric (e.g., 100).

    • <DATASET_HEX>: The hex string you copied from the OTBR console.

    • : The 8-digit PIN obtained from the setup payload.

    • : The long discriminator from the setup payload.

  • Troubleshooting Attestation Failure: If pairing fails due to device attestation, you have two options:

    • Option A (Recommended): Provide PAA Certificates: Download the root PAA certificate from the CSA DCL for the device’s issuer (found in the logs) and use the --paa-trust-store-path flag to point to its location.

    • Option B (Workaround): Bypass Attestation: If providing certificates is unsuccessful, you can bypass the check entirely by adding the following flag to the command:

      •   chip-tool pairing ble-thread <NODE_ID> hex:<DATASET_HEX> <PIN> <DISCRIMINATOR> --bypass-attestation-verifier true

5. Open a Commissioning Window for OpenHAB

After the lock is on the Thread network, open a temporary “window” to allow OpenHAB to add it as a second controller.

  • On the Raspberry Pi:

    1. Run the Open Commissioning Window Command: This generates a new, temporary setup code.

          chip-tool pairing open-commissioning-window <NODE_ID> 1 300 1000 <DISCRIMINATOR>
      • Use the same <NODE_ID> and from the previous step.

    2. Copy the Temporary Code: The command will output a new manual setup code and QR code. Use this to add the device to OpenHAB.

6. Add the Lock to OpenHAB

The final step is to bring the commissioned lock into your OpenHAB system.

  • Troubleshooting IPv6 on Raspberry Pi:

    • Adding a Matter device to OpenHAB requires a fully working IPv6 configuration. If you face issues, ensure IPv6 is enabled in OpenHAB’s network settings.

    • A critical fix may be to adjust the max_plen setting to ensure the Raspberry Pi correctly processes IPv6 router advertisements.

          sudo sysctl -w net.ipv6.conf.eth0.accept_ra_rt_info_max_plen=128

    • After applying this, confirm you can ping the device’s IPv6 address from the Raspberry Pi before proceeding.

  • In the OpenHAB UI:

    1. Navigate to Things, click the plus icon (+), and choose the Matter Binding. This will take you to the “Add a new Thing: matter” section.

    2. In the Scan Input field, enter the temporary pairing code generated by the open-commissioning-window command, then click the Scan button.

    3. Complete the pairing wizard.

    4. The Aqara U200 lite will appear in your Inbox. Add it as a Thing and proceed to configure its channels and items as needed.

1 Like
Matter - Thread - Zigbee - Some questions
What gateway for OH+Thread (Matter)