들어가며
Zephyr에 대한 학습 의지는 매우 높았으나, 러닝커브가 상당히 높다는 느낌이 들어 번번히 포기해왔다.
거의 5년 넘게 LED만 켜고, 끝내고 그 이상 진전하지 못했던 것 같다.
그러나, 여러 AI 도구들을 활용하면서, 자연스럽게 러닝커브들을 낮춰주는 도움이 되었던 것 같다.
앞으로 Zephyr에 대한 글들은 Claude와 소통하면서 만들어내는 내용들이며, 추후 활용에 사용하려는 목적이 있다.
이번엔 다르다: Docker + Dev Container
그동안에는 Zephyr 공식 Getting Started 가이드 [https://docs.zephyrproject.org/latest/develop/getting_started/index.html]를 따라 수동으로 환경을 구축했다.
West 설치하고, Python 패키지 설치하고, 툴체인 다운로드하고, 환경변수 설정하고... 명령어 하나하나 타이핑하면서 말이다.
내가 생각 했을 때, 이 방식의 문제는 명확했다:
협업이 어렵다
협업을 할때 모두 동일한 개발 환경 또는 SDK를 써야하는데, 단순히 명령어 따라치는 수준으로는 한계가 있다고 판단했다.
재현성이 없다
한참 지나서 다시 Zephyr를 쓰려고 하면 기억이 안 난다. "이 명령어를 쳤더라"는 기억나는데, 순서가 헷갈린다. 그래서 다시 처음부터 설치하려고 하면, 이미 설치된 다른 프로젝트의 Python 패키지들과 충돌이 나고, PATH가 꼬이고... 결국 시스템을 초기화하고 싶어진다.
이것이 Docker + Dev Container 를 선택한 이유다.
VSCode의 Dev Containers 확장을 사용하면, 사전 구성된 Docker 컨테이너 안에서 개발할 수 있다. Zephyr 프로젝트에서 공식 제공하는 Docker 이미지(zephyrprojectrtos/ci)를 쓰면, 모든 툴체인과 의존성이 이미 설정되어 있다.
더 중요한 것은 .devcontainer/devcontainer.json 파일 하나가 전체 개발 환경을 정의한다는 점이다. 이 파일을 Git에 커밋하면, 팀원 누구나 동일한 환경을 5분 안에 구축할 수 있다. Python 버전이 다르거나, West 버전이 안 맞는 일은 일어나지 않는다.
프로젝트 뼈대 만들기
먼저 프로젝트 구조를 잡는다. Zephyr는 West라는 메타 빌드 시스템을 사용하는데, 이게 처음엔 낯설지만 익숙해지면 편하다.
mkdir ~/my-zephyr-project
cd ~/my-zephyr-project
mkdir application
가장 중요한 파일은 application/west.yml이다. 이 파일이 "어떤 버전의 Zephyr를 쓸 것인가"를 정의한다:
manifest:
remotes:
- name: zephyrproject-rtos
url-base: https://github.com/zephyrproject-rtos
projects:
- name: zephyr
remote: zephyrproject-rtos
revision: v4.1.0
import: true
self:
path: application
여기서 revision: v4.1.0이 핵심이다. Zephyr는 약 3개월마다 새 버전이 나오는데, 각 버전마다 기능과 안정성이 다르다.
버전 선택 가이드:
LTS(Long Term Support) 버전: 장기 지원이 필요한 상용 제품에 적합. 예: v3.7 (LTS)
최신 stable 버전: 새로운 기능을 써보고 싶을 때. 예: v4.1.0
main 브랜치: 최신 개발 버전. 불안정할 수 있음. revision: main
중요: Docker CI 이미지 버전
이 글에서는 Zephyr v4.1.0과 Docker 이미지 zephyrprojectrtos/ci:v0.26.13을 사용한다.
솔직히, 정확한 매칭 방법은 잘 모르겠다.
CI 이미지에는 Zephyr SDK(툴체인), CMake, Python 패키지 등이 포함되어 있고, 버전이 맞지 않으면 빌드 오류가 날 수 있다는 것은 확실하다. 하지만 "Zephyr v4.1.0에는 정확히 어느 CI 이미지를 써야 한다"는 공식 문서를 찾기 어려웠다.
내가 한 방법:
Zephyr v4.1.0을 쓰고 싶었음
Docker Hub에서 비슷한 시기에 나온 이미지 확인
v0.26.13을 시도 → 빌드 성공 ✅
계속 사용 중
권장사항:
이 글의 조합(v4.1.0 + v0.26.13)을 그대로 쓰면 작동함 (직접 테스트함)
다른 버전을 쓰고 싶다면:
최신 Zephyr + 최신 CI 이미지부터 시도
빌드 오류가 나면 CI 이미지 버전을 조금씩 바꿔보기
또는 Zephyr Discord에서 물어보기
이제 Docker를 이용해 Zephyr 소스를 받는다:
docker run -it --rm
-v $(pwd):/workspace
-w /workspace/application
zephyrprojectrtos/ci:v0.26.13
/bin/bash
컨테이너 안에서:
west init -l .
west update # 오래 걸려요
exit
이 명령 하나로 Zephyr 전체 소스 트리가 다운로드된다. 크기가 상당하니 느긋하게 기다리자.
최종 프로젝트 구조와 Git 관리
west update가 완료되면 다음과 같은 구조가 생성된다:
my-zephyr-project/
├── .devcontainer/
│ └── devcontainer.json # Dev Container 설정
├── .vscode/
│ ├── settings.json # VSCode 설정
│ └── tasks.json # 빌드 태스크
├── .west/ # West 메타데이터 (gitignore)
│ └── config
├── application/ # 실제 개발 코드 (Git 관리 대상)
│ ├── west.yml # Zephyr 버전 정의
│ ├── src/
│ │ └── main.c # 애플리케이션 코드
│ ├── CMakeLists.txt # 빌드 설정
│ ├── prj.conf # 프로젝트 설정
│ └── README.md
├── zephyr/ # Zephyr OS 소스 (gitignore)
│ ├── arch/
│ ├── boards/
│ ├── drivers/
│ └── ...
├── modules/ # 외부 모듈들 (gitignore)
│ ├── hal/
│ ├── crypto/
│ └── ...
└── .gitignore
West Manifest 방식의 핵심 장점
여기서 중요한 것은 Git에 올려야 할 것과 올리지 말아야 할 것을 구분하는 것이다.
Git에 올릴 것 (실제 개발 코드만):
my-zephyr-project/
├── .devcontainer/
├── .vscode/
├── application/ # 이것만!
│ ├── west.yml
│ ├── src/
│ ├── CMakeLists.txt
│ └── prj.conf
└── .gitignore
Git에 올리지 않을 것 (.gitignore):
West가 생성하는 것들
.west/
zephyr/
modules/
bootloader/
tools/
빌드 결과물
build/
*.pyc
pycache/
왜 이렇게 하는가?
용량 절약: zephyr/와 modules/는 수백 MB에 달한다. 이걸 Git에 올리면 저장소가 거대해진다.
협업 간소화: 팀원이 프로젝트를 받으면:단 두 명령어로 완전히 동일한 환경이 구축된다.
git clone https://github.com/yourname/my-zephyr-project cd my-zephyr-project # 동일한 Zephyr 환경 구축 (west.yml 기반) docker run -it --rm \ -v $(pwd):/workspace \ -w /workspace/application \ zephyrprojectrtos/ci:v0.26.13 \ bash -c "west init -l . && west update"
버전 관리 명확성: west.yml의 revision: v4.1.0이 Zephyr 버전을 명시한다. 누가 언제 clone하든 항상 동일한 버전의 Zephyr를 사용한다.
업데이트 용이성: Zephyr를 v4.2.0으로 업그레이드하고 싶다면?
west update # 다시 실행
application/west.yml revision: v4.2.0 # 이것만 바꾸고
다른 application 추가하기
하나의 Zephyr workspace에 여러 프로젝트를 관리할 수도 있다:
my-zephyr-project/
├── application/ # 첫 번째 프로젝트
│ └── west.yml
├── sensor-project/ # 두 번째 프로젝트
│ ├── src/
│ ├── CMakeLists.txt
│ └── prj.conf
├── motor-controller/ # 세 번째 프로젝트
│ ├── src/
│ ├── CMakeLists.txt
│ └── prj.conf
└── zephyr/ # 공유하는 Zephyr 소스
이렇게 하면 하나의 Zephyr 설치로 여러 프로젝트를 개발할 수 있다.








































