Matter Relay Actuator

This firmware is a Matter relay actuator. It creates one Matter On/Off endpoint, and writes to that endpoint's OnOff attribute control one physical relay GPIO.

---

Implementation

• Relay GPIO: GPIO22
• Relay default boot state: off
• Relay polarity: active-high
• RGB LED GPIO: GPIO21 on ESP32, GPIO8 on targets where GPIO8 is not reserved for SPI flash
• Matter behavior: one On/Off endpoint controls the relay GPIO

---

Prerequisites

Hardware

• ESP32-DevKitM-1 or another board
• 5V 1-Channel Relay Module or another module
• Power Supply and wires

Software

• Ubuntu 24.04 or 24.10
• ESP-IDF 5.3
• ESP-Matter 1.4

---

Getting Started

ESP-IDF Setup

Step 1. Install Prerequisites for ESP-IDF:

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

Step 2. Get ESP-IDF:

mkdir -p ~/esp
cd ~/esp
git clone -b v5.3 --recursive https://github.com/espressif/esp-idf.git

Step 3. Set up the Tools:

cd ~/esp/esp-idf
./install.sh all

Step 4. Configure Environment Variables:

alias get_idf='. $HOME/esp/esp-idf/export.sh'

Add this line to ~/.bashrc to persist the alias.

Step 5. Refresh Configuration:

source ~/.bashrc

Running get_idf will now set up or refresh the esp-idf environment in any terminal session.

ESP-Matter Setup

Step 1. Install Prerequisites for Matter:

sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev

Step 2. Clone the esp-matter Repository:

cd ~/esp/
git clone -b release/v1.4 --recursive https://github.com/espressif/esp-matter.git

Step 3. Bootstrap esp-matter:

cd esp-matter
./install.sh

Step 4. Configure Environment Variables:

alias get_matter='. $HOME/esp/esp-matter/export.sh'

Add this line to ~/.bashrc to persist the alias.

Step 5. Refresh Configuration:

source ~/.bashrc

Running get_matter will now set up or refresh the esp-matter environment in any terminal session.

---

Wiring

To connect the relay module to the ESP32, use the following wiring instructions:

Relay Module Pinout

• DC+ (Power Supply Positive): Connect to the 3.3V pin on the ESP32.
• DC- (Power Supply Negative): Connect to the GND pin on the ESP32.
• IN (Input Signal): Connect to the GPIO22 pin on the ESP32.

Relay Switch Terminals

• COM (Common Terminal): Connect to the positive terminal of the power supply (red wire from the power source). This is the common connection that feeds power into the relay.
• NO (Normally Open): Connect to the red wire of the fan (positive wire). When the relay is activated, it closes the circuit, sending power to the fan.
• NC (Normally Closed): Leave this unconnected.

Controlled Device

• Black Wire (Negative): Connect directly to the negative terminal of the power supply (black wire).
• Red Wire (Positive): Connect to the NO terminal on the relay.

---

Build and Flash

Step 1. Clone the Repository

git clone https://github.com/albert-gee/matter_relay.git
cd matter_relay

Step 2. Set up the Environment

get_idf
get_matter

Step 3. Set ESP32 as the Target Device

This command creates a new sdkconfig file in the root directory of the project:

idf.py set-target esp32

Step 4. Build the Project

idf.py build

Step 5. Determine Serial Port

Connect the ESP32 board to the computer and check under which serial port the board is visible. Serial ports typically follow the /dev/tty pattern.

Step 6. Flash the Project to the Target

idf.py -p <PORT> flash

Step 7. Launch the IDF Monitor Application

Press CTRL+] to exit.

idf.py -p <PORT> monitor

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

References

• Espressif Matter Documentation
• Matter Protocol Specification