MATTER 개발을 위한 CHIPTOOL

개발팁|2026. 2. 5. 18:40

CHIP Tool(chip-tool)은 Matter 프로토콜을 테스트하고 디바이스를 제어하기 위한 공식 커맨드라인 도구이며, GitHub의 Matter(Connected Home over IP) 오픈소스 저장소에서 직접 빌드하거나 배포판 패키지를 통해 얻을 수 있습니다. 즉, Matter 개발자가 기기를 네트워크에 등록(commissioning)하고 클러스터 명령을 보내거나 이벤트를 구독하는 데 사용하는 핵심 툴입니다.

1. Chip-tool이란 무엇인가?

Chip-tool은 Matter 오픈소스 프로젝트(Project Connected Home over IP, 줄여서 CHIP)에서 제공하는 Matter 컨트롤러(Controller) 레퍼런스 구현체입니다.

쉽게 말해, 스마트폰 앱이나 스마트 허브 대신 PC(Linux/macOS) 터미널에서 명령어를 입력해 Matter 기기를 제어하고 테스트할 수 있는 도구라고 보시면 됩니다.

주요 기능

  • Commissioning (커미셔닝): 새로운 Matter 기기를 네트워크에 연결하고 보안 인증을 수행합니다.
  • Cluster Control (클러스터 제어): 기기의 On/Off, 밝기 조절, 온도 읽기 등 구체적인 기능을 실행합니다.
  • Monitoring: 네트워크 상의 기기 상태 변화나 이벤트 로그를 실시간으로 확인합니다.

2. 어디에서 얻을 수 있는가?

Chip-tool은 별도의 설치 파일(.exe 등)로 배포되지 않고, Matter 공식 GitHub 저장소에서 소스 코드를 내려받아 직접 빌드해야 합니다.

획득 방법 및 절차

  1. 공식 저장소 접속: ConnectedHomeIP GitHub에서 전체 프로젝트를 클론(Clone)합니다.
  2. 환경 설정: 프로젝트 내 scripts/checkout_submodules.py 등을 실행하여 필요한 의존성을 설치합니다.
  3. 빌드: examples/chip-tool 디렉토리로 이동하여 gn 및 ninja 빌드 도구를 사용해 컴파일합니다.
# GitHub 저장소 클론
git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip/examples/chip-tool

# 빌드
gn gen out/chip-tool
ninja -C out/chip-tool

# 실행 예시: 특정 디바이스 On/Off 제어
./chip-tool onoff on 1234 1

 

참고: 
빌드 환경: Linux/Ubuntu 환경에서 가장 안정적으로 빌드 가능. Windows/맥OS도 지원되지만 설정이 복잡할 수 있음.
chip-tool은 개발 및 테스트용으로 설계되었으며, 실제 상용 컨트롤러 앱(예: Google Home, Apple HomeKit)과는 별개입니다.

 

3. 왜 Chip-tool을 사용하나요?

실제 상용 앱(Apple Home, Google Home 등)은 내부 동작 과정을 상세히 보여주지 않지만, Chip-tool은 모든 데이터 패킷과 에러 메시지를 터미널에 출력해 줍니다. 따라서 개발 중 통신 오류가 발생했을 때 원인을 파악하기에 최적입니다.

사용 예시 (명령어 형태)

Bash
 
# 기기 전원 켜기 예시
./chip-tool onoff on <node_id> <endpoint_id>

  설치 순서

 

Matter 개발의 핵심인 chip-tool을 빌드하기 위한 가이드를 정리해 드립니다. 가장 권장되는 환경은 Ubuntu 22.04 LTS (또는 WSL2)입니다.

1. 필수 설치 패키지 (Prerequisites)

빌드 전에 시스템에 필요한 도구와 라이브러리를 먼저 설치해야 합니다. 터미널에서 아래 명령어를 실행하세요.

 

sudo apt-get update
sudo apt-get install -y git gcc g++ python3 python3-venv python3-pip \
    pkg-config libssl-dev libdbus-1-dev libglib2.0-dev libavahi-client-dev \
    ninja-build python3-dev python3-setuptools libreadline-dev libncurses5-dev \
    libncursesw5-dev unzip

기타 필수 도구: gn (Google의 빌드 도구)이 필요하지만, 이는 보통 Matter 스크립트 실행 과정에서 자동으로 관리됩니다.

 

2. 소스 코드 내려받기

Matter 공식 저장소는 용량이 매우 크므로, 서브모듈(Submodules)까지 모두 포함하여 클론해야 합니다.

Bash
 
git clone --recursive https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip

이미 클론을 하셨다면, 아래 명령어로 서브모듈을 업데이트하세요:

Bash
 
git submodule update --init

3. 환경 설정 (Bootstrap)

Matter 개발 환경을 활성화하는 단계입니다. 이 과정에서 GN, Ninja, 필요한 Python 가상 환경 등이 자동으로 구성됩니다.

Bash
 
# 이 작업은 시간이 다소 소요될 수 있습니다.
source scripts/bootstrap.sh

4. Chip-tool 빌드하기

이제 gn과 ninja를 사용하여 chip-tool을 컴파일합니다.

Bash
 
# 빌드용 출력 디렉토리 생성 및 설정
gn gen out/debug

# ninja를 이용한 컴파일 (컴퓨터 사양에 따라 수 분 소요)
ninja -C out/debug chip-tool

빌드가 완료되면 out/debug/chip-tool 경로에 실행 파일이 생성됩니다.

5. 실행 테스트

빌드가 잘 되었는지 확인하기 위해 도움말 명령어를 실행해 보세요.

Bash
 
./out/debug/chip-tool

 

  예제

 

Matter 기기를 처음 연결할 때는 Commissioning(커미셔닝) 과정을 거쳐야 하며, 이후에 **Cluster(기능)**를 제어하게 됩니다. 가장 대중적인 On/Off 플러그/조명을 예로 들어 설명해 드릴게요.

1. 기기 커미셔닝 (네트워크 연결)

기기를 Matter 네트워크에 할당하는 작업입니다. 기기가 블루투스(BLE) 광고 모드이거나 IP 네트워크(Wi-Fi/Ethernet)에 연결 준비가 되어 있어야 합니다.

방법 A: Wi-Fi 기기 커미셔닝

기기의 Setup PIN 코드(예: 20202021)와 Wi-Fi 정보를 입력합니다.

Bash
 
# 형식: ./chip-tool pairing ble-wifi <node_id> <ssid> <password> <setup_pin_code> <discriminator>
./chip-tool pairing ble-wifi 1 "MyWiFiName" "MyPassword123" 20202021 3840

방법 B: 이미 IP가 할당된 기기 (Ethernet)

Bash
 
# 형식: ./chip-tool pairing onnetwork <node_id> <setup_pin_code>
./chip-tool pairing onnetwork 1 20202021
  • node_id (1): 앞으로 내가 이 기기를 부를 번호입니다. (내 마음대로 지정)
  • setup_pin_code (20202021): 기기에 적혀있는 8자리 보안 코드입니다.

2. 기기 제어 (Cluster Control)

커미셔닝이 완료되었다면, 지정한 node_id를 이용해 명령을 내립니다.

조명/플러그 켜기 및 끄기

Matter에서는 On/Off 기능을 onoff 클러스터라고 부릅니다.

Bash
 
# 1번 기기(Node ID 1)의 1번 엔드포인트(Endpoint 1)를 켜기
./chip-tool onoff on 1 1

# 1번 기기 끄기
./chip-tool onoff off 1 1

# 상태 토글(반전) 하기
./chip-tool onoff toggle 1 1

상태 읽기 (Attribute Read)

기기가 현재 켜져 있는지 꺼져 있는지 상태값을 가져옵니다.

Bash
 
./chip-tool onoff read on-off 1 1

3. 유용한 모니터링 명령

개발 중에 기기의 상태 변화를 실시간으로 보고 싶을 때 유용합니다.

작업 명령어 예시 설명
속성 구독 ./chip-tool onoff subscribe on-off 1 10 1 1 상태가 변할 때마다 자동으로 보고받음
기기 정보 확인 ./chip-tool basicinformation read vendor-name 1 0 제조사 이름을 읽어옴
페어링 해제 ./chip-tool pairing unpair 1 컨트롤러에서 해당 기기 정보를 삭제

실행 시 팁

  • 엔드포인트(Endpoint): 보통 전구 하나라면 1번입니다. 멀티탭처럼 구가 여러 개라면 1, 2, 3번 순으로 늘어납니다.
  • 로그 확인: 명령어를 실행하면 터미널에 굉장히 많은 로그가 찍힙니다. [BLE] 또는 [CASESession] 관련 로그가 보인다면 통신이 정상적으로 이루어지고 있다는 증거입니다.

 

'개발팁' 카테고리의 다른 글

ESP32 AT command를 이용한 간단한 Socket 통신 시험  (0) 2026.01.30
ESP32-C3/C6/H2 MINI 모듈 기본 하드웨어 설계  (0) 2026.01.28

티스토리툴바