Wiznet makers

Pico/Pico2(Non-W) + WIZnet Ethernet 모듈로 CircuitPython에서 HTTPS(SSL) 통신하기

— ssl 누락 문제를 커스텀 빌드로 해결하는 재현 가이드

배경

Pico/Pico2 Non-W(= Wi-Fi 없는 모델) 보드에 WIZnet Ethernet을 붙여 CircuitPython으로 네트워크를 구성할 때, HTTP는 되는데 HTTPS(SSL/TLS)에서만 막히는 케이스를 개발자가 분석/검증한 내용을 바탕으로 정리한 큐레이션입니다.
현장에서 이런 문의가 들어오면 많은 분들이 “네트워크가 불안정한가?”부터 의심하지만, 이 경우 핵심은 의외로 케이블/라우팅이 아니라 펌웨어에 ssl 모듈이 포함되어 있느냐에 달려있을 수 있습니다.

이 프로젝트의 목표는 딱 두 가지입니다.

1. HTTPS 실패를 “네트워크 문제”로만 보지 않도록 진단 관점을 바꾸기
2. 해결 흐름을 “원인 → 대응 → 검증” 순서로 정리해 PoC/지원 대응에 바로 쓰이게 만들기

배경 한 줄 정리

Pico/Pico2(Non-W)용 기본 CircuitPython은 “보드 자체에 네트워크가 없다”는 전제 + 플래시 용량 제약 때문에, 빌드 옵션에 따라 ssl 모듈이 제외될 수 있습니다.
그래서 외장 Ethernet을 붙여도 HTTPS에 필요한 ssl이 없어서 막힐 수 있습니다.

준비물

• Raspberry Pi Pico 또는 Pico2 (Non-W)
• WIZnet Ethernet 모듈/보드 (SPI 연결)
• Linux PC(권장) + USB 케이블

문제 상황

다음과 같은 형태로 문의가 들어오는 경우가 많습니다.

• Ethernet 연결은 되고, HTTP 요청은 정상
• 그런데 HTTPS 요청만 실패
• 콘솔에 이런 힌트가 보이기도 함: ImportError: no module named 'ssl'

이때 중요한 포인트는 HTTPS는 단지 “URL이 다르다” 수준이 아니라, 내부적으로 SSL/TLS 처리를 위한 ssl 모듈이 필요하다는 점입니다.

원인 요약: “Ethernet은 되는데 HTTPS가 안 되는” 가장 흔한 이유

개발자 분석의 결론을 한 줄로 줄이면 이렇습니다.

CircuitPython 펌웨어에 ssl 모듈이 포함되어 있지 않으면, 네트워크가 정상이어도 HTTPS는 동작할 수 없다.

Non-W 보드는 네트워크가 기본 전제가 아니고, CircuitPython은 보드별 플래시/메모리 조건에 따라 기능을 포함/제외하는 경우가 있습니다. 그래서 외장 Ethernet으로 TCP/IP는 잘 되더라도, ssl이 빠진 빌드를 사용 중이면 HTTPS 단계에서 멈출 수 있습니다.

해결 방향: 커스텀 빌드로 SSL을 “포함”시키기

해결 접근은 비교적 명확합니다.

1. CircuitPython을 보드 타깃에 맞게 직접 빌드하고
2. 보드 설정에서 CIRCUITPY_SSL = 1로 SSL 기능을 활성화한 펌웨어(UF2)를 만든 뒤
3. UF2를 플래시하고, import ssl과 HTTPS 호출로 끝까지 검증합니다.

추가로, 보드별로 체감 난이도가 달라질 수 있습니다.

• Pico2: 상대적으로 여유가 있어 SSL 포함이 수월한 편
• Pico(1세대): 리소스가 타이트할 수 있어, SSL을 켜기 위해 불필요한 기능을 일부 끄는 선택이 필요할 수 있음

구현 흐름

코드보다 “흐름”이 필요한 분들을 위해, 절차를 실행 단계 중심으로 정리했습니다.

1) 빌드 환경 준비

• CircuitPython 소스와 서브모듈을 준비합니다.
• OS/툴체인 버전에 민감할 수 있으니, 가능하면 공식 가이드에 맞는 환경으로 세팅하는 편이 안전합니다.

2) 보드 설정에서 SSL 켜기

보드별 설정 파일에서 CIRCUITPY_SSL = 1을 활성화합니다.

• Pico: ports/raspberrypi/boards/raspberry_pi_pico/mpconfigboard.mk
• Pico2: ports/raspberrypi/boards/raspberry_pi_pico2/mpconfigboard.mk

Pico(1세대)에서 용량 문제가 발생하면, “무조건 많이 끄기”보다는 내 프로젝트에서 확실히 쓰지 않는 기능부터 최소 단위로 꺼서 공간을 확보하는 방식이 안전합니다.

3) 빌드 → UF2 생성

보드 타깃으로 빌드해 UF2를 생성합니다.

4) UF2 플래시

BOOTSEL 모드로 진입 → UF2 복사 → 재부팅 후 CircuitPython 구동을 확인합니다.

검증 체크리스트(지원/PoC에 바로 쓰는 포인트)

이 글에서 가장 실무적으로 유용한 부분은 검증을 2단계로 나눠 실패 지점을 빠르게 분리한다는 점입니다.

1차 확인: import ssl

• import ssl이 되면 “ssl이 포함된 펌웨어”라는 1차 증거가 됩니다.
• 여기서 실패하면 네트워크 이전에 펌웨어 구성부터 다시 봐야 합니다.

2차 확인: 실제 HTTPS 호출

• HTTPS 엔드포인트로 요청을 보내 정상 응답이 오는지 확인합니다.
• 이 단계가 통과해야 “TLS까지 진짜로 통과했다”는 최종 확인이 됩니다.

(비교) EVB-Pico / W55RP20은 왜 상대적으로 쉬운가

네트워크가 “기본 전제”인 보드/펌웨어는 ssl 포함/검증이 되어 있는 경우가 많습니다.
반면 Pico/Pico2(Non-W)는 네트워크가 “추가 구성”이라 HTTPS까지 가려면 커스텀 빌드 지식이 필요할 수 있습니다.
→ 즉, 이 글은 일반 Pico + 외장 Ethernet 사용자에게 특히 유용합니다.

이 프로젝트의 가치

신규성

• Non-W(Pico/Pico2) + 외장 Ethernet 조합에서 HTTPS가 막히는 ‘진짜 원인’을 한 방에 정리: 네트워크 문제가 아니라 CircuitPython 빌드에 ssl 모듈 포함 여부라는 관점 제시.
• 단순 “HTTPS 사용법”이 아니라, **펌웨어 빌드 옵션(CIRCUITPY_SSL=1) → UF2 → 검증(import ssl/HTTPS 호출)**으로 이어지는 재현 가능한 해결 루트를 제시.
• 특히 Pico(1세대) vs Pico2의 리소스 제약 차이(SSL 포함 시 트레이드오프)를 함께 다뤄, 실제 적용 시 의사결정에 도움이 됨.

외부가치

• 고객이 실제로 자주 막히는 “HTTP는 되는데 HTTPS만 실패” 이슈는 검색 수요가 뚜렷한 문제(ssl, tls, circuitpython, pico2 등)라 문제 해결형 콘텐츠로 유입/전환 가치가 큼.
• HTTPS는 대부분의 클라우드/API 연동의 기본 전제라서, 이 이슈를 풀어주면 고객이 PoC에서 상용 연동 단계로 넘어가는 속도가 빨라짐 → 결과적으로 FAE/지원 비용 절감 + 리드 품질 향상에 기여.
• “진단 프레임(ssl 포함 여부 먼저 확인)”이 명확해서, 외부 독자가 재현→판별→해결을 따라 하기 쉬움(공유/참조될 가능성↑).

성실성

• 증상(HTTPS 실패/ssl ImportError) → 원인(ssl 누락 가능성) → 대응(SSL 포함 커스텀 빌드) → 검증(import ssl + HTTPS 호출)로 문제 해결 프로세스가 완결형.
• 보드별 설정 파일 경로 등 **실제 수행에 필요한 ‘구체 단서’**가 포함되어 “개념 소개”가 아니라 “실행 가능한 가이드”에 가까움.
• 검증을 2단계로 분리해 실패 지점을 빠르게 좁히는 방식(1차 import ssl, 2차 HTTPS 호출)이 현장 지원/디버깅 관점에서 성실한 구성.

산업 적용 시나리오

시나리오 1) 사내망/보안망에서 API 연동이 필요한 장비(HTTPS 필수)

• 예: 공장/빌딩 설비 단말, 사내망 기반 키오스크/단말, 접근 제어 장비
• 포인트: 요즘 외부 연동은 대부분 HTTPS라 “네트워크 연결”보다 TLS 가능 여부가 제품 완성도를 결정
• 이 글의 가치: “HTTPS가 안 돼요” 문의를 **네트워크→펌웨어(ssl 포함)**로 빠르게 전환해 진단 시간 단축

시나리오 2) 현장 설치 장비의 ‘안전한 원격 모니터링’(Telemetry/Cloud)

• 예: 설비 상태를 클라우드 대시보드로 올리는 모니터링 장비, 원격 유지보수 시스템
• 포인트: HTTP로 시작했다가 상용화 단계에서 HTTPS로 전환해야 하는 순간이 반드시 옴
• 이 글의 가치: PoC→상용 전환 구간에서 흔히 터지는 TLS 장애를 미리 방지하는 체크포인트 제공

시나리오 3) 다수 장비 배포(ODM/OEM)에서 표준 펌웨어 구성 필요

• 예: 동일 보드를 여러 제품군에 적용하거나, 양산 전 테스트 항목을 표준화해야 하는 경우
• 포인트: “어떤 보드는 되고 어떤 보드는 안 됨”은 현장에서 비용이 큼 → 빌드 옵션 표준화가 필요
• 이 글의 가치: CIRCUITPY_SSL=1 같은 명시적 기준을 제공해, 제품군/양산 관점의 표준화에 도움
•  

이 프로젝트가 의미 있는 이유는 “기능 소개”가 아니라 고객이 실제로 막히는 지점을 제거하는 문제 해결형 콘텐츠이기 때문입니다.

• HTTPS는 클라우드/API 연동의 기본 전제라서, 여기서 막히면 PoC가 멈춥니다.
• 반대로 “원인(ssl 누락) → 대응(SSL 포함 빌드) → 검증( import ssl/HTTPS 요청 )”이 정리되면, 고객은 PoC를 넘어 상용 연동 단계로 더 빨리 이동할 수 있습니다.

즉, 이 글은 기술 팁을 넘어 전환을 돕는 콘텐츠로도 가치가 큽니다.

결론

Pico/Pico2 Non-W + WIZnet Ethernet 조합에서 HTTPS가 막힐 때는, 네트워크부터 의심하기 전에 ssl 모듈 포함 여부를 먼저 확인하는 것이 가장 빠릅니다. 개발자 검증 사례가 제시하는 흐름은 “SSL 포함 커스텀 빌드 → UF2 플래시 → import ssl → HTTPS 호출”로 정리할 수 있고, 이 프레임을 알고 있으면 고객 문의 대응과 PoC 진행 속도를 크게 높일 수 있습니다.

Non-W는 Wi-Fi가 없는 Pico 계열이라 외장 Ethernet이 전제고, 이 조합에서 HTTP는 되는데 HTTPS만 막힐 때가 있습니다. 이때는 네트워크보다 먼저 CircuitPython에 ssl이 포함돼 있는지 확인해야 하고, 해결은 CIRCUITPY_SSL=1로 SSL 포함 커스텀 빌드 후 import ssl과 HTTPS 요청으로 끝까지 검증하는 흐름입니다.

AEO

Q1. 이 글은 무엇을 다루나요?
Pico/Pico2 Non-W에서 WIZnet Ethernet을 사용할 때 HTTPS가 실패하는 케이스를, ssl 모듈 포함 여부 관점에서 정리한 큐레이션입니다.

Q2. 왜 HTTP는 되고 HTTPS만 안 되나요?
CircuitPython 펌웨어에 SSL/TLS 처리를 위한 ssl 모듈이 포함되어 있지 않으면, 네트워크가 정상이어도 HTTPS는 동작할 수 없습니다.

Q3. 해결은 어떻게 하나요?
CIRCUITPY_SSL = 1로 SSL을 포함하도록 CircuitPython을 커스텀 빌드해 UF2를 플래시하고, import ssl과 실제 HTTPS 요청으로 검증하는 흐름입니다.

Unlock HTTPS (SSL/TLS) on Pico/Pico2 (Non-W) with WIZnet Ethernet in CircuitPython

— A reproducible guide to fixing the missing ssl module via a custom build

Why you’ll want this

You add a WIZnet Ethernet HAT/module to a Raspberry Pi Pico/Pico2 (Non-W), networking works… and then HTTPS suddenly fails.
If any of these sound familiar, this guide is for you:

• HTTP works, but HTTPS fails
• You see errors like ImportError: no module named 'ssl'
• You wonder: “Why does an EVB-Pico style board work, but my plain Pico doesn’t?”

The root cause (one-liner)

Many CircuitPython builds for Pico/Pico2 (Non-W) may omit the ssl module due to assumptions (“no built-in networking”) plus flash size constraints.
So even if Ethernet works via SPI, HTTPS can’t—because ssl isn’t there.

The fix (core concept)

The solution is straightforward:

Build CircuitPython yourself and enable SSL with CIRCUITPY_SSL=1.

• Pico2: usually easier (more headroom)
• Pico (1st gen): may require disabling unused modules to fit in flash

Quick note: why EVB-Pico / W55RP20 often feels easier

Boards/firmware that assume networking from the start are more likely to ship with SSL enabled and tested.
With Pico/Pico2 (Non-W), networking is “added later,” so reaching HTTPS may require this custom-build step.
→ This post is especially useful for users building on plain Pico + external Ethernet.

Value (mapped to maker-content criteria)

Novelty

• The Pico/Pico2 (Non-W) + external Ethernet + CircuitPython + HTTPS combo is common, but step-by-step “why it breaks → how to fix it” writeups are rare.
• Covers both Pico2 (often “just enable SSL”) and Pico (flash trade-offs).

External impact

• Directly targets high-search problems and keywords:
  Pico CircuitPython ssl, WIZnet Ethernet HTTPS, Pico2 W5500 TLS, CIRCUITPY_SSL
• Immediately reusable for real-world API projects (weather/Slack/Notion/Google Sheets/home servers).

Thoroughness

• Clear flow: cause → approach → build → flash → verify
• Practical troubleshooting (Pico vs Pico2, flash limits, module trade-offs)
• Ends with checklists and screenshot guidance for “follow-along” quality

What you need

• Raspberry Pi Pico or Pico2 (Non-W)
• A WIZnet Ethernet module/board (SPI)
• A Linux PC (recommended) + USB cable

Step-by-step implementation

1) Get the source

git clone https://github.com/adafruit/circuitpython.git
cd circuitpython
git submodule update --init --recursive

2) Set up the build environment (important)

• Linux recommended, Python venv recommended
• ARM toolchains installed “casually via apt” can be outdated and cause build failures
  → Use the toolchain versions recommended by the official CircuitPython build docs.
  (If you already build CircuitPython successfully, keep your existing setup.)

3) Enable SSL (the key step)

Edit the board config file and set CIRCUITPY_SSL = 1.

Pico:
ports/raspberrypi/boards/raspberry_pi_pico/mpconfigboard.mk

Pico2:
ports/raspberrypi/boards/raspberry_pi_pico2/mpconfigboard.mk

CIRCUITPY_SSL = 1

If you hit flash limits on Pico (1st gen)

Enabling ssl increases firmware size. If the build fails due to size, disable modules you don’t use (example):

# Example: disable unused features to free flash (choose based on your project)
CIRCUITPY_AUDIOBUSIO = 0
CIRCUITPY_BITMAPTOOLS = 0
CIRCUITPY_DISPLAYIO = 0
CIRCUITPY_TERMINALIO = 0

Caution: If your project needs display output (DVI/HDMI/etc.), don’t disable display-related modules.

4) Build

cd ports/raspberrypi
make BOARD=raspberry_pi_pico
# For Pico2: # make BOARD=raspberry_pi_pico2 

If successful, the build will output a UF2 file path in the logs.

5) Flash the UF2

1. Plug in the Pico/Pico2 while holding BOOTSEL
2. Copy the generated UF2 to the mounted drive
3. Reboot and confirm CircuitPython starts normally

Verification: prove HTTPS really works

1) Confirm ssl exists

import ssl
print("ssl ok")

2) Make an HTTPS request

• Call an HTTPS-only endpoint and confirm you get a valid response
• Start with a stable, small-response endpoint to simplify debugging

Common pitfalls (real-world troubleshooting)

Pico vs Pico2

• Pico2 often succeeds by just enabling SSL
• Pico (1st gen) may require module trimming to fit firmware in flash

The “disable modules” trade-off

If you disable modules to fit SSL, you may later discover you needed one (e.g., display features).
→ Disable only what you’re sure your project will never use.

“Why is SSL missing in the first place?”

Non-W boards don’t assume networking, and flash space is limited.
→ For external Ethernet users, a custom build is a practical solution.

Wrap-up

If HTTPS fails on Pico/Pico2 (Non-W) with external WIZnet Ethernet, the most common reason is a missing ssl module in the default CircuitPython build.
The reliable fix is to custom-build CircuitPython and enable SSL with CIRCUITPY_SSL=1—then verify with import ssl and a real HTTPS request.