WIZnet-PICO-C Docker Build System

A cross-platform, Docker-based build system for WIZnet Ethernet boards with RP2040/RP2350.

COMPONENTS

PROJECT DESCRIPTION

WIZnet-PICO-C Docker 빌드 시스템

RP2040/RP2350 기반 WIZnet 이더넷 보드를 위한 크로스 플랫폼 Docker 빌드 시스템

개요

문제점

WIZnet 이더넷 보드용 펌웨어를 빌드하려면 전통적으로:

Pico SDK 및 의존성 설치 필요
툴체인 설정 (arm-none-eabi-gcc)
여러 라이브러리 버전 관리
플랫폼별 빌드 스크립트 작성

이는 초보자에게 진입 장벽이 되고, 환경 설정에 시간을 낭비하게 합니다.

해결책

WIZnet-PICO-C Docker 빌드 시스템은 다음을 제공합니다:

한 번의 명령으로 빌드: 수동 설정 불필요
크로스 플랫폼: Windows, Linux, macOS 지원
격리된 환경: Docker 컨테이너로 충돌 방지
성능 최적화: tmpfs + ccache로 빠른 빌드

지원 하드웨어

10종 보드:

WIZnet Ethernet HAT (W5100S)
W5100S-EVB-Pico
W5500-EVB-Pico ← 권장
W55RP20-EVB-Pico (이더넷 내장 SiP)
W6100-EVB-Pico (IPv6)
W6300-EVB-Pico (QSPI)
W5100S-EVB-Pico2 (RP2350)
W5500-EVB-Pico2 (RP2350)
W6100-EVB-Pico2 (RP2350)
W6300-EVB-Pico2 (RP2350)

16종 예제:

기본: loopback, udp, http, tcp_server_multi_socket
프로토콜: dhcp_dns, sntp, mqtt, tftp, netbios, pppoe, upnp
보안: tcp_client_over_ssl, tcp_server_over_ssl
고급: udp_multicast, can, network_install

주요 특징

🚀 빠른 빌드 성능

tmpfs: RAM에 빌드 디렉토리 생성 (20GB)
ccache: 컴파일 캐시 (재빌드 시 100% 적중)
병렬 빌드: 16개 동시 작업

🌐 크로스 플랫폼

Windows: PowerShell 스크립트 (build.ps1)
Linux: Bash 스크립트 (build.sh)
macOS: Bash 스크립트 (build.sh)

👥 사용자 친화적

Interactive 모드: 초보자를 위한 안내 UI
명령줄 모드: 고급 사용자를 위한 빠른 빌드
단일 예제 빌드: 필요한 것만 빌드

🔧 고급 기능

CleanOutput: 전체 클린 없이 빠른 재빌드
호스트 examples: 호스트에서 예제 편집, 컨테이너에서 빌드
자동 초기화: 서브모듈 자동 처리

시작하기

사전 요구사항

필수:

Docker Desktop (Windows/macOS) 또는 Docker Engine (Linux)
Git
20GB 여유 RAM (tmpfs용)
5GB 여유 디스크 공간 (ccache용)

선택:

Windows: PowerShell 5.1+ (Windows 10/11에 기본 설치)
Linux/macOS: Bash 4.0+

설치

1단계: Docker 설치

Windows/macOS: Docker Desktop에서 다운로드

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install docker.io
sudo usermod -aG docker $USER
# 로그아웃 후 다시 로그인

2단계: 저장소 클론

git clone https://github.com/your-username/wiznet-pico-c-docker.git
cd wiznet-pico-c-docker

3단계: Docker 확인

# Windows
docker --version

# Linux/macOS
docker --version

사용법 - Interactive 모드

Interactive 모드는 초보자를 위한 안내 UI를 제공합니다.

1단계: Interactive 모드 실행

Windows:

powershell -ExecutionPolicy Bypass -File .\build.ps1 -Interactive

Linux/macOS:

./build.sh -i

2단계: 보드 선택

시스템이 10종의 지원 보드를 표시합니다:

예시:

W5500-EVB-Pico를 위해 3 선택 (권장)

3단계: 예제 선택

난이도 별표(⭐)가 표시된 16종 예제 중 선택:

옵션:

0: 전체 16개 예제 빌드 (약 10분)
1-16: 특정 예제 빌드
다중 선택: 1 2 3 (loopback, udp, http 빌드)

예시:

HTTP 서버를 위해 3 선택 (⭐⭐ 난이도)

4단계: 빌드 완료

빌드 결과:

빌드 시간: 2분 6초
출력: wizchip_http_server.uf2 (103KB)
위치: out/ 디렉토리
tmpfs 사용량: 27MB

다음 단계:

W5500-EVB-Pico를 USB로 연결
BOOTSEL 버튼을 누른 채 RESET 버튼 클릭
out/wizchip_http_server.uf2를 드래그앤드롭
시리얼 터미널 열기 (115200 baud)

사용법 - 명령줄 모드

명령줄 모드는 고급 사용자를 위한 빠른 빌드를 제공합니다.

전체 예제 빌드

Windows:

powershell -ExecutionPolicy Bypass -File .\build.ps1 -Board W5500_EVB_PICO -All

Linux/macOS:

./build.sh -b W5500_EVB_PICO -a

빌드 진행:

Docker 이미지 pull: simryang/w55rp20:latest
서브모듈 초기화
CMake 설정
Ninja 빌드 (16 병렬 작업)

빌드 결과:

빌드 시간: 33분 24초
출력: 16개 예제, 총 20개 .uf2 파일
tmpfs 사용량: 129MB (최대)

단일 예제 빌드

Windows:

powershell -ExecutionPolicy Bypass -File .\build.ps1 -Board W5500_EVB_PICO -Example http

Linux/macOS:

./build.sh -b W5500_EVB_PICO -e http

HTTP 예제만 빌드:

타겟: wizchip_http_server
다른 예제는 빌드하지 않음

여러 예제 빌드

Windows:

powershell -ExecutionPolicy Bypass -File .\build.ps1 -Board W5500_EVB_PICO -Example "http mqtt"

Linux/macOS:

./build.sh -b W5500_EVB_PICO -e "http mqtt"

빌드 결과:

wizchip_http_server.uf2
wizchip_mqtt_publish.uf2
wizchip_mqtt_publish_subscribe.uf2
wizchip_mqtt_subscribe.uf2

성능 최적화

ccache: 100% 캐시 적중

동일한 코드를 재빌드할 때, ccache는 거의 즉시 컴파일을 제공합니다.

성능 비교:

빌드 타입	첫 빌드	재빌드 (ccache)	속도 향상
단일 예제 (http)	2분 6초	25초	5배 빠름
전체 예제	33분 24초	~2-3분	11배 빠름

ccache 통계:

적중: 142 / 142 (100%)
캐시 크기: 0.03GB / 5.00GB (0.66%)
tmpfs 사용량: 27MB (단일 예제)

tmpfs: RAM 기반 빌드

RAM(tmpfs)에서 빌드하는 것이 디스크보다 훨씬 빠릅니다:

tmpfs vs 디스크:

tmpfs (RAM): ~2분 (단일 예제)
SSD: ~3-4분
HDD: ~5-8분

tmpfs 설정:

크기: 20GB (설정 가능)
마운트: /work/src/build
빌드 후 자동 정리

고급 기능

CleanOutput: 빠른 재빌드

일반 clean은 모든 것을 삭제하여 33분 재빌드가 필요합니다.

CleanOutput은 빌드 출력만 삭제하고 빌드 캐시를 보존합니다:

Windows:

powershell -ExecutionPolicy Bypass -File .\build.ps1 -CleanOutput

Linux/macOS:

./build.sh -co

결과:

삭제: out/ 디렉토리 (8개 파일)
보존: WIZnet-PICO-C/build/ (CMake 캐시)
다음 빌드: 33분 대신 1-2분

사용 사례:

다른 보드 테스트
Debug/Release 빌드 전환
디스크 공간 정리

호스트 Examples: 편집 및 빌드

전체 저장소를 포크하는 대신, examples를 호스트로 복사:

1단계: Examples 초기화

Windows:

powershell -ExecutionPolicy Bypass -File .\build.ps1 -InitExamples

Linux/macOS:

./build.sh --init-examples

WIZnet-PICO-C/examples/를 ./examples/로 복사합니다.

2단계: Examples 편집

vi ./examples/http/w5x00_http_server.c
# 코드 수정

3단계: 수정된 Examples로 빌드

Windows:

powershell -ExecutionPolicy Bypass -File .\build.ps1 -Board W5500_EVB_PICO -All

Linux/macOS:

./build.sh -b W5500_EVB_PICO -a

빌드 시스템이 자동으로 ./examples/를 컨테이너에 마운트하여 수정된 코드를 사용합니다.

장점:

서브모듈 관리 불필요
쉬운 버전 관리 (Git)
빠른 반복 개발

성능 분석

CPU 활용률

Docker 빌드 시스템이 모든 CPU 코어를 효율적으로 활용합니다.

테스트 환경:

CPU: AMD Ryzen 7 5700G (8코어, 16스레드)
RAM: 32GB
OS: Windows 11

빌드 전: 유휴 상태

측정값:

CPU 사용률: 1%
클럭 속도: 3.98GHz
프로세스: 434
스레드: 7129

빌드 중: 전체 부하

측정값:

CPU 사용률: 61% (최대)
클럭 속도: 4.36GHz (부스트)
16개 스레드 모두 활용
Ninja 병렬 빌드: -j 16

빌드 성능:

단일 코어: ~20분
16코어: 2-3분 (ccache 활성화)
병렬 효율: ~85%

빌드 특성

CPU 사용 패턴:

CMake 설정: 낮은 CPU (단일 스레드)
Ninja 컴파일: 높은 CPU (병렬)
링킹: 중간 CPU (제한적 병렬화)

권장사항:

4코어 CPU: 양호 (8-10분 빌드)
8코어 CPU: 우수 (2-3분 빌드)
16코어 CPU: 최적 (ccache로 1-2분 빌드)

문제 해결

일반적인 문제

문제 1: Docker 미실행

오류:

Error: Docker daemon not running

해결:

Windows/macOS: Docker Desktop 실행
Linux: sudo systemctl start docker

문제 2: 권한 거부 (Linux)

오류:

permission denied while trying to connect to the Docker daemon

해결:

sudo usermod -aG docker $USER
# 로그아웃 후 다시 로그인

문제 3: 메모리 부족

오류:

ninja: fatal error: fork: Cannot allocate memory

해결:

tmpfs 크기 줄이기: build.sh 또는 build.ps1 편집
TMPFS_SIZE=20g를 TMPFS_SIZE=10g로 변경
또는 병렬 작업 수 줄이기: JOBS=8

문제 4: 서브모듈 미초기화

오류:

Pico SDK submodule not initialized!

해결: 빌드 시스템이 자동으로 처리합니다. 실패할 경우:

cd WIZnet-PICO-C
git submodule update --init --recursive
cd ..

문제 5: 빌드 타겟을 찾을 수 없음 (Windows)

오류:

ninja: error: unknown target 'wizchip_udp_multicast_sender'

해결: 최신 버전으로 업데이트:

git pull

타겟 매핑 버그가 수정되었습니다 (커밋 4feccb6).

도움 받기

GitHub 이슈: 버그 신고
WIZnet 포럼: 질문하기
문서: README.md

향후 계획

Python 통합 (계획됨)

build.ps1과 build.sh 간의 코드 중복을 제거하기 위해 계획 중:

1단계: Python 스크립트

모든 플랫폼을 위한 단일 build.py
build.ps1 / build.sh는 얇은 래퍼로
Python 3.6+ 필요 (Docker 사용자에게 표준)

2단계: PyInstaller 바이너리 (선택)

build.exe (Windows)
build (Linux)
build (macOS)
Python 설치 불필요

장점:

단일 코드베이스 유지
기능 추가가 쉬움
크로스 플랫폼 일관성 향상

자세한 내용은 FUTURE_PLAN_PYTHON_INTEGRATION.md 참조.

계획된 기능

GitHub Actions 통합 (CI/CD)
모든 보드를 위한 사전 빌드 Docker 이미지
원격 빌드를 위한 웹 UI
커스텀 보드 지원
FreeRTOS 예제 통합

결론

WIZnet-PICO-C Docker 빌드 시스템은 WIZnet 이더넷 보드용 펌웨어 개발을 단순화합니다:

✅ 설정 불필요: Docker가 모든 것을 처리 ✅ 빠른 빌드: tmpfs + ccache = 25초 ✅ 크로스 플랫폼: Windows, Linux, macOS ✅ 사용자 친화적: 초보자를 위한 Interactive 모드 ✅ 유연함: 단일 또는 전체 예제

시작하기:

git clone https://github.com/your-username/wiznet-pico-c-docker.git
cd wiznet-pico-c-docker
./build.sh -i  # Linux/macOS

질문이 있으신가요?

문서: README.md
이슈: GitHub Issues

저자

구현/리눅스 환경 테스트/글 내용 작성 : Joseph

윈도우 환경 테스트/실행 이미지 수집 : Aimee

Documents

wiznet_pico_c_dockerbuild

Comments Write

WIZnet-PICO-C Docker Build System

WIZnet-PICO-C Docker 빌드 시스템

목차

개요

문제점

해결책

지원 하드웨어

주요 특징

🚀 빠른 빌드 성능

🌐 크로스 플랫폼

👥 사용자 친화적

🔧 고급 기능

시작하기

사전 요구사항

설치

사용법 - Interactive 모드

1단계: Interactive 모드 실행

2단계: 보드 선택

3단계: 예제 선택

4단계: 빌드 완료

사용법 - 명령줄 모드

전체 예제 빌드

단일 예제 빌드

여러 예제 빌드

성능 최적화

ccache: 100% 캐시 적중

tmpfs: RAM 기반 빌드

고급 기능

CleanOutput: 빠른 재빌드

호스트 Examples: 편집 및 빌드

성능 분석

CPU 활용률

빌드 전: 유휴 상태

빌드 중: 전체 부하

빌드 특성

문제 해결

일반적인 문제

문제 1: Docker 미실행

문제 2: 권한 거부 (Linux)

문제 3: 메모리 부족

문제 4: 서브모듈 미초기화

문제 5: 빌드 타겟을 찾을 수 없음 (Windows)

도움 받기

향후 계획

Python 통합 (계획됨)

계획된 기능

결론

저자