Device Tree Overlay로 HAT/외부 장치 지원 추가하기

대상: Raspberry Pi 5 + Linux (예: Raspberry Pi OS / Ubuntu 등) 환경에서, GPIO 확장 보드(HAT), SPI/I2C 장치, UART, 특정 하드웨어 추가 등을 위해 Device Tree 설정을 직접 다루고 싶은 개발자
환경: Raspberry Pi 5, 부트 파티션이 /boot/firmware (또는 Raspberry Pi OS 기본 구조), dtc (device tree compiler) 사용 가능

1. 왜 Device Tree Overlay가 필요한가

Raspberry Pi 커널은 기본적인 GPIO, SPI, I2C, UART 등 하드웨어 구성을 하나의 DTB(Device Tree Blob)로 정의합니다. (위키독스)
하지만 각 사용자 HAT 또는 외부 장치는 “표준 GPIO 배열 + 특정 핀 매핑 + 장치 노드 추가”가 필요할 수 있습니다. 기본 DTB를 직접 바꾸기보다는 Overlay 방식이 권장됩니다. (bootlin.com)
Overlay를 사용하면, 커널 업데이트 후에도 설정이 유지되고, 관리가 용이하며, 여러 보드 구성을 공존시킬 수 있습니다. (bootlin.com)

2. 전체 흐름 개요

사용자 HAT/외부 장치에 맞는 .dts (Device Tree Source) 또는 오버레이 파일 작성
dtc (device-tree-compiler) 로 .dtbo (Device Tree Blob, Overlay) 컴파일
/boot/firmware/overlays/ (또는 /boot/overlays/) 폴더에 .dtbo 배치
/boot/firmware/config.txt (혹은 /boot/config.txt) 에 dtoverlay= 항목 추가 → 재부팅
장치가 정상적으로 인식되는지 확인

3. 구체적인 단계

(1) 필요한 도구 설치

sudo apt update
sudo apt install device-tree-compiler

DT 컴파일러(dtc)가 있어야 .dts → .dtbo 변환이 가능. (위키독스)

(2) Overlay DTS 파일 작성 예시

예: 간단한 GPIO 확장 보드 또는 I2C 장치 연결을 위한 overlay 예시

/dts-v1/;
/plugin/;

/ {
    compatible = "brcm,bcm2712";  /* Raspberry Pi 5 의 SoC에 맞게 변경 가능 */

    fragment@0 {
        target = <&i2c1>;    /* 예: i2c1 인터페이스 사용 시 */
        __overlay__ {
            status = "okay";

            my_sensor: sensor@50 {
                compatible = "vendor,my_sensor";
                reg = <0x50>;
                /* 필요한 속성들 추가 */
            };
        };
    }

    fragment@1 {
        target = <&gpio>;    /* GPIO 제어가 필요하다면 */
        __overlay__ {
            pinctrl-0 = <&my_pins>;
            pinctrl-names = "default";
        };
    }
};

/plugin/ 지시자: THIS DTS가 오버레이임을 나타냄 (개준생의 공부 일지)
fragment@N 단위: 메인 DTB에 “덧붙일 변경점/추가점”을 정의
target 또는 target-path 로 어떤 노드(버스, GPIO, I2C 등)를 변경할지 지정 (개준생의 공부 일지)

필요한 설정은 HAT 설계나 연결된 장치 사양에 따라 달라집니다 (예: I2C, SPI, UART, GPIO, IRQ, 레귤레이터 등).

(3) DTS → DTBO 컴파일

작성한 my_overlay.dts 를 .dtbo 로 변환:

dtc -@ -I dts -O dtb -o my_overlay.dtbo my_overlay.dts

-@ : overlay 플러그인을 위한 옵션
.dtbo 파일 생성됨 (bootlin.com)

(4) DTBO 파일 설치

컴파일된 .dtbo 파일을 Raspberry Pi의 부트 파티션 내 overlays 폴더에 복사:

sudo cp my_overlay.dtbo /boot/firmware/overlays/
# (혹은 /boot/overlays/ 경로 — 배포판/OS에 따라 다름)
sudo chmod 644 /boot/firmware/overlays/my_overlay.dtbo

(5) config.txt 수정

/boot/firmware/config.txt (혹은 /boot/config.txt) 에 다음 줄 추가:

dtoverlay=my_overlay

extension .dtbo 는 생략
여러 개 overlay 필요 시, 각 overlay마다 따로 dtoverlay= 줄 반복 dtoverlay=overlay1 dtoverlay=overlay2,param=value
필요시 dtparam= 으로 간단한 파라미터 설정 가능 (예: SPI, I2C enable/disable) (Raspberry Pi)

저장 후 리부팅

(6) 적용 결과 확인

/proc/device-tree/ 아래에 overlay 적용된 노드가 보이는지 확인
dmesg 또는 ls /dev 등으로 실제 드라이버/장치 노드가 로드되었는지 확인
예: I2C 장치라면 /dev/i2c-1, SPI라면 /dev/spidev…, GPIO 핀 제어 가능 여부 등

4. Raspberry Pi 5 / HAT + M.2 HAT+ 관련 주의점

Raspberry Pi 5의 경우, PCIe 기반 M.2 HAT+ 보드가 HAT 스펙을 따르지만, 반드시 overlay가 필요한 것은 아닙니다. 일부 HAT+는 EEPROM ID만 있고, 별도의 DT overlay 없이도 PCIe 디바이스로 동작합니다. (forums.raspberrypi.com)
즉, “overlay가 반드시 있어야 한다” 는 건 아니지만, GPIO나 I2C, SPI, 추가 핀매핑 등이 있는 HAT은 overlay를 통해 정의하는 것이 일반적입니다.
커스텀 하드웨어라면, 위에서 설명한 overlay 작성 → 컴파일 → 적용 방식이 가장 유지보수/이식성 측면에서 안전합니다.

5. 풀 커스텀 DTB 만들기 (옵션)

만약 Overlay만으로 원하는 구성이 충분하지 않거나, 매우 특별한 보드라면, 메인 DTB(DTS)를 직접 수정한 후 새 DTB를 빌드해도 됩니다. (위키독스)
예: device_tree=my_custom.dtb 를 config.txt 에 지정하면 복합 하드웨어 정의를 완전 커스터마이즈할 수 있음. 다만 유지보수의 복잡성은 증가합니다. (위키독스)

6. 자주 만나는 실수 & 팁

문제 / 실수	원인 / 설명	해결 팁
Overlay 적용 후 부팅실패 / “Unable to merge overlay: err:11”	DTS 문법 오류, fragment target 잘못, incompatible compatible string 등 (Stack Overflow)	DTS 문법 재검토, compatible / target 정확히 설정, dtc 컴파일 경고 확인
`dtoverlay=` 추가했는데 동작 안 함	`.dtbo` 파일이 `/boot/firmware/overlays/` 에 없거나 경로 오타	dtbo 위치 및 이름 확인, 파일 권한 확인
HAT+ 장치인데 overlay가 없어도 동작	PCIe DET_WAKE 기반 자동 인식 (예: NVMe 카드) (forums.raspberrypi.com)	overlay 없이도 동작 가능 여부 확인
커널 업데이트 시 설정 날아감	직접 DTB 수정했을 경우	Overlay 방식 사용이 유지보수에 유리

7. 예시 – SPI OLED HAT 오버레이

예: SPI OLED HAT (예: SSD1306) 를 붙인다고 가정할 때:

ssd1306-oled.dts

/dts-v1/;
/plugin/;

&spi0 {
    status = "okay";
    spidev@0 {
        compatible = "solomon,ssd1306";
        reg = <0>;
        spi-max-frequency = <10000000>;
        rotation = <0>;
        width = <128>;
        height = <64>;
    };
};

컴파일 & 설치 & config.txt 수정 후 부팅 시 /dev/spidev0.0 또는 OLED 드라이버가 자동 로드되는 구조를 구성할 수 있습니다.

8. 요약

Raspberry Pi (5 포함) 에서 HAT / 외부 장치 추가 시 Device Tree Overlay 방식이 권장됨
`.dts → .dtbo → config.txt dtoverlay=… → 재부팅** 이 일반적인 흐름
Overlay 방식은 업데이트에 유연하고 유지보수에 유리함
HAT+ (PCIe) 같은 경우에는 overlay 없이 동작할 수도 있지만, GPIO / I2C / SPI 같은 주변장치가 있다면 overlay로 명시하는 것이 좋음