Getting Started with Connected Home over IP (CHIP)

1. Introduction

Matter is a new standard within the Connectivity Standards Alliance (formerly Zigbee Alliance). This industry unifying standard is a promise of reliable, secure connectivity—a seal of approval that devices will work seamlessly together, today and tomorrow

The goal of this standard is to simplify development for manufacturers and increase compatibility for consumers. It is actively being developed on GitHub, in the Connected Home over IP project, which is built around a shared belief that smart home devices should be secure, reliable, and seamless to use. By building upon Internet Protocol (IP), the project aims to enable communication across smart home devices, mobile apps, and cloud services and to define a specific set of IP-based networking technologies for device certification.

Except as otherwise noted, the content of this Codelab is licensed under the

Apache 2.0 License. See the Project CHIP open-source license for more info.

This Codelab will walk you through setting up a Wi-Fi device using the ESP32 development board, adding on/off functionality to it, and controlling it with a command line interface.

What you'll learn

How to connect and control a CHIP enabled device.
How to add more functionality to an example device application.

What you'll need

A basic knowledge of Linux
An ESP32 development board
A Linux machine with "git" installed

2. Getting started

Serial port terminals

You should be familiar with how to connect to a serial port through a terminal. This Codelab uses screen and provides a usage overview, but any other terminal software can be used.

Linux machine

This Codelab was designed to use an x86-based 64-bit Linux machine to execute the chip tool, and to flash all development boards. All steps were tested on Ubuntu 20.04.2.0 LTS.

ESP32 development board

This codelab uses one of these ESP32 development boards:

ESP32-DevkitC
ESP32-WROVER-KIT V4.1
M5Stack ESP32 Series Basic Core IoT Development Kit

You will need to connect the development kit to your Linux machine using a USB cable to flash firmware and access the device logs.

3. Clone the repository

To check out the version of the source code that is compatible with this document, use these steps to clone the repository:

$ git clone git@github.com:project-chip/connectedhomeip.git
$ cd connectedhomeip
$ git checkout 1de2b73bb4123af5f184eac54d1b1d76985b4f62
$ git submodule update --init

Then, follow the steps in the "Prerequisites" and "Build Preparation" sections of the Build Documentation on GitHub for your platform. Once complete, continue reading here.

Apply the patch for the Codelab

With this patch we'll remove the callback to handle the on/off command from CHIP. Later we will go through it, and add it back in step by step.

$ git fetch origin ce1e0ab44c367bc9d5907115e09a4c45fc6d8c96
$ git cherry-pick ce1e0ab44c367bc9d5907115e09a4c45fc6d8c96

4. Build the CHIP Client Example

In order to talk to CHIP devices from your host machine, you'll need to build chip-tool for your host.

Follow the instructions on GitHub for building chip-tool.

One you have chip-tool, you will use it to perform operations such as toggling device endpoints on and off.

Refer to the chip-tool documentation and source code on GitHub for more information about different chip-tool operations.

5. Build the All Clusters Example

After you've set up your host and built chip-tool, you can build and run the All Clusters Example for ESP32.

First, change to the All Clusters Example directory.

$ cd examples/all-clusters-app/esp32

Then, follow the instructions on GitHub until you are instructed to run this command:

$ idf make menuconfig

When running this command, you will be presented with the configuration editor for the example.

Configure the Board Type

Navigate to Demo → Device Type and select the board you are building for.

Disable Rendezvous Mode

Disabling Rendezvous Mode allows the device to communicate with chip-tool over an insecure channel. In the configuration menu, navigate to Demo → Rendezvous Mode and set the mode to Bypass:

Configure the Wi-Fi SSID and Password

In the configuration menu, navigate to Component config → CHIP Device Layer → WiFi Station Options, and set these two options for your Wi-Fi network:

Default WiFi SSID
Default WiFi Password

Building and Flashing

With these configuration settings in place, build and flash the example application.

Substitute "USB0" below with the tty your development board is attached to. If you have more than one serial cable plugged into your host machine, it may have a different tty (e.g. /dev/ttyUSB1 or /dev/ttyUSB2). Continue making this substitution anywhere else you see USB0 in this document.

$ idf make
$ idf make erase_flash ESPPORT=/dev/ttyUSB0
$ idf make flash ESPPORT=/dev/ttyUSB0

The above steps are also available on the CHIP All Clusters Example README.

6. Enable the OnOff command

Open DeviceCallbacks.cpp located in examples/all-clusters-app/esp32/main in any editor. Once open in the editor, navigate to the "DeviceCallbacks::PostAttributeChangeCallback()" function.

When sending an on-off command from chip-tool, the device should receive ZCL_ON_OFF_CLUSTER_ID events. To handle these events, we add it to the event callback that handles different clusterIDs.

void DeviceCallbacks::PostAttributeChangeCallback(...)
{
    ...

    switch (clusterId)
    {
    case ZCL_ON_OFF_CLUSTER_ID:
        break;

    default:
        ESP_LOGI(TAG, "Unhandled cluster ID: %d", clusterId);
        break;
    }
    ...
}

Every cluster supports many attributes. We would like to support a simple on and off functionality. So check the attributeId of ZCL_ON_OFF_ATTRIBUTE_ID in the code. It should be empty.

void DeviceCallbacks::PostAttributeChangeCallback(...)
{
    ...

    switch (clusterId)
    {
    case ZCL_ON_OFF_CLUSTER_ID:
        if (attributeId == ZCL_ON_OFF_ATTRIBUTE_ID) {

        } else {
          ESP_LOGI(TAG, "Unhandled attribute ID: %d", attributeId);
        }
        break;

    default:
        ESP_LOGI(TAG, "Unhandled cluster ID: %d", clusterId);
        break;
    }

    ...
}

Add the function call to control the status of LED on the development kit if the clusterId and the attributeId are correct.

void DeviceCallbacks::PostAttributeChangeCallback(...)
{
    ...

    switch (clusterId)
    {
    case ZCL_ON_OFF_CLUSTER_ID:
        if (attributeId == ZCL_ON_OFF_ATTRIBUTE_ID) {
          statusLED1.Set(*value);
        } else {
          ESP_LOGI(TAG, "Unhandled attribute ID: %d", attributeId);
        }
        break;


    default:
        ESP_LOGI(TAG, "Unhandled cluster ID: %d", clusterId);
        break;
    }

    ...
}

Save the file, then build the application and flash the development kit again, using the same process in Building and Flashing in the previous step:

$ idf make
$ idf make erase_flash ESPPORT=/dev/ttyUSB0
$ idf make flash ESPPORT=/dev/ttyUSB0

7. Running the Example Application

Connect the USB cable from the ESP32 board to your host machine, and start a serial terminal. One good program to use is screen, and you can see the serial output from the ESP32 by running this command:

$ screen /dev/ttyUSB0 115200

After the device boots and connects to Wi-Fi, it will display its IP address in the serial console. You will need this to interact with the device using chip-tool.

In the case above, the IP address is 192.168.117.134, and the device is listening on port 11097.

Using this IP address and port, establish a connection to the device, bypassing the pairing step:

$ cd examples/chip-tool
$ ./out/debug/chip-tool pairing bypass 192.168.117.134 11097

Now you can toggle endpoint 1 with the following command:

$ ./out/debug/chip-tool onoff toggle 1

On the ESP32 DevKitC, this will toggle the signal on GPIO2:

In the picture above, a 1.8V/20mA red LED is wired to GPIO2, with a 75 Ohm resistor in serial.

On the ESP32-WROVER-KIT, the above command will toggle a virtual green LED on the upper-left of the display:

On the M5Stack board, the above command will toggle a virtual green LED on the upper-left of the display:

8. Congratulations

You've successfully controlled the development kit using CHIP. Awesome!

In this Codelab you learned how to:

Enable OnOff functionality on your development kit.
Control the development kit by CHIP controller tool.

Learn more

Here are some ideas you can implement to go deeper:

Edit the ZAP file to expand the capabilities of the functionality.
Add ZCL_IDENTIFY_CLUSTER_ID functionality to the DeviceCallbacks.cpp file
The specification defines the ZigBee Cluster Library.
Check out GitHub for the latest on Project CHIP and buildwithmatter.com for the latest on Matter.