ESP32로 LED 전광판 만들기 (4) — 증상을 덮은 것과 원인을 없앤 것은 다르다Building an ESP32 LED Signboard (4) — Masking a Symptom Is Not the Same as Fixing the Cause

구성을 바꾸자 증상이 돌아왔다Changing the Hardware Setup Brought the Symptom Back

3편 에서 초기 버전을 완료했다. 실제 공장 설치를 준비하며 컨트롤러와 패널 구성을 바꿨다.

In Part 3, I finished the initial build. While preparing the signboard for actual factory installation, I upgraded the controller board and panel chain.

레벨 시프터가 내장된 보드로 바꾸고 배선도 리본으로 정리했으니 신호는 더 깨끗해졌을 텐데, 배경의 푸르스름한 잔상이 다시 나타났다.

With a dedicated level-shifted controller board and clean ribbon cables, signal integrity should have been much better—yet the bluish background ghosting returned immediately.

이번에는 변수를 하나씩 되돌렸다Reverting Variables One by One

3편에서는 우연히 발견한 현상(가로 스크롤이 지나가면 사라진다)에서 바로 해결책으로 갔다. 이번에는 순서를 바꿨다. 원인 후보를 하나씩 원래 값으로 되돌려 재현되는지 확인했다.

In Part 3, I jumped straight from an accidental observation (that a full horizontal scroll cleared the tint) to a visual workaround. This time I reversed the process: I reverted candidate variables one at a time to see which exact change reproduced the bug.

라이브러리 소스를 읽고 나서야 이해됐다Reading the Library Source Explained Why

ESP32-HUB75-MatrixPanel-DMA 라이브러리는 driver != SHIFTREG(0) 이면 begin() 에서 shiftDriver() 를 호출한다. 그런데 ICN2038S, FM6124, FM6126A 세 값이 전부 동일한 fm6124init() 으로 분기한다.

In the ESP32-HUB75-MatrixPanel-DMA library, setting driver != SHIFTREG(0) causes begin() to call shiftDriver(). Inside that function, ICN2038S, FM6124, and FM6126A all branch to the exact same fm6124init() routine.

이 초기화 루틴은 패널에 글로벌 전류 게인 레지스터(REG1)를 거의 최대값으로 기입한다. 그런데 내가 쓰는 패널의 실제 드라이버는 이 레지스터 포맷을 따르지 않는다. 기입된 값이 엉뚱하게 해석되면서 블랙 레벨 자체가 떠 버린 것이다.

That initialization sequence writes a near-maximum value into the panel's global current gain register (REG1). However, the actual driver silicon on my panels does not follow the FM6124 register format—so the written bits were misinterpreted, raising the black level across the panel.

// [원인] driver != SHIFTREG → shiftDriver() → fm6124init() → 전류 게인 레지스터 오기입
// mxconfig.driver = HUB75_I2S_CFG::ICN2038S;   // ❌ 패널 라벨이 ICN2038S여도 이 옵션과는 비호환

constexpr HUB75_I2S_CFG::shift_driver PANEL_DRIVER = HUB75_I2S_CFG::SHIFTREG;   // ✅ 확정 해결
mxconfig.driver           = PANEL_DRIVER;
mxconfig.i2sspeed         = HUB75_I2S_CFG::HZ_8M;   // 512px 체인 안전 속도 명시
mxconfig.min_refresh_rate = 60;

// [Root Cause] driver != SHIFTREG → shiftDriver() → fm6124init() → bad current gain register write
// mxconfig.driver = HUB75_I2S_CFG::ICN2038S;   // ❌ Incompatible even if the chip silkscreen says ICN2038S

constexpr HUB75_I2S_CFG::shift_driver PANEL_DRIVER = HUB75_I2S_CFG::SHIFTREG;   // ✅ Confirmed fix
mxconfig.driver           = PANEL_DRIVER;
mxconfig.i2sspeed         = HUB75_I2S_CFG::HZ_8M;   // Explicit safe clock for 512px chain
mxconfig.min_refresh_rate = 60;

왜 하필 파란색만 뜨는가Why Only Blue Glowed

블랙 레벨이 떴다면 R, G, B가 고르게 떠야 할 것 같은데 유독 푸르스름했다. HUB75 리본 케이블의 핀 배치를 보면 이유가 보인다.

If the black level was elevated, you would expect R, G, and B to glow equally—yet the tint was distinctly blue. Looking at the 16-pin HUB75 ribbon cable pinout explains why:

 1 R1  |  2 G1
 3 B1  |  4 GND    ← B1이 GND 바로 옆
 5 R2  |  6 G2
 7 B2  |  8 E      ← B2가 E 바로 옆 (1/8 스캔 패널은 내부 GND)
 9 A   | 10 B
11 C   | 12 D      ← 1/8 스캔 패널은 내부 GND
13 CLK | 14 LAT
15 OE  | 16 GND

 1 R1  |  2 G1
 3 B1  |  4 GND    ← B1 sits directly adjacent to GND
 5 R2  |  6 G2
 7 B2  |  8 E      ← B2 sits adjacent to E (tied to internal GND on 1/8-scan panels)
 9 A   | 10 B
11 C   | 12 D      ← Tied to internal GND on 1/8-scan panels
13 CLK | 14 LAT
15 OE  | 16 GND

Blue 두 라인(B1=3번, B2=7번)만 GND 계열 핀과 물리적으로 인접해 있다. 따라서 블랙 레벨이 조금만 떠도 R/G보다 B가 먼저 문턱값을 넘어 미세하게 점등되고, 결과적으로 "푸르스름한 배경"으로 보인다.

Only the two Blue lines (B1 on pin 3, B2 on pin 7) are physically adjacent to ground-referenced pins. Combined with Blue LEDs' lower forward voltage threshold relative to Red/Green driver biases when the current gain register is misconfigured, a slight shift in black level pushes the Blue channels across their conduction threshold first.

함께 정정한 오진 두 건Two More Misdiagnoses Corrected Along the Way

• digitalWrite(pin, LOW) 는 GND가 아니다. 74AHCT245의 LOW 출력은 0.1~0.3V이고 임피던스도 수십 Ω이다. 실제 접지 전위차가 있다면 이 방법으로는 제거되지 않는다.
• GPIO17은 HUB75 16번이 아니라 I2C의 SCL이다. Matrix Portal S3에서 HUB75 4번·16번은 보드상 하드와이어 GND이며, 소프트웨어로 접지 고정이 필요한 라인은 D(Pin12=GPIO35), E(Pin8=GPIO21) 두 개뿐이다. 기존의 GPIO17 LOW 클램프 코드는 HUB75와 무관하게 I2C 버스만 정지시키고 있었다.

• digitalWrite(pin, LOW) is not true GND. A LOW output from a 74AHCT245 sits at 0.1–0.3V with tens of ohms of output impedance. If there is a ground potential difference, clamping a GPIO LOW will not eliminate it.
• GPIO17 is I2C SCL, not HUB75 pin 16. On the Matrix Portal S3, HUB75 pins 4 and 16 are hardwired to GND on the PCB; the only address lines that need software LOW clamping on 1/8-scan panels are D (Pin 12 = GPIO35) and E (Pin 8 = GPIO21). Clamping GPIO17 LOW had nothing to do with HUB75—it was just stalling the onboard I2C bus.

그리고 화면이 굳었다And Then the Display Froze Solid

리팩터링을 하고 나니 새 증상이 생겼다. 와이파이가 연결된 직후 화면이 멈춘 채 굳었다. 증상은 하나였지만 원인은 두 개가 겹쳐 있었다.

After refactoring the initialization code, a new bug appeared: right after Wi-Fi connected, the display froze completely. It looked like a single symptom, but two separate causes were stacked on top of each other.

원인 A — 스캔이 렌더링 루프를 잡고 있었다Cause A — Wi-Fi Scanning Blocked the Rendering Loop

WiFiMulti::run() 은 전 채널을 스캔하는 블로킹 호출이라 수 초간 CPU를 점유한다. 이걸 loop()(코어 1)에서 불렀기 때문에 스캔이 도는 동안 I2S 렌더링이 통째로 정지했다. 신호가 약할수록 스캔이 길어져 더 오래 멈췄다.

WiFiMulti::run() performs a blocking scan across all Wi-Fi channels, holding the CPU for several seconds. Because it was called inside loop() on Core 1, I2S frame updates stalled whenever a scan ran. Weaker signal conditions made scans take even longer.

3편에서 HTTP 수신만 코어 0으로 뺐는데, 스캔과 연결도 블로킹이라는 걸 놓쳤다. 모든 블로킹 네트워크 작업을 코어 0 전담 NetTask 로 격리했다. loop() 는 volatile 상태값만 읽고 절대 블로킹되지 않는다.

In Part 3, I had moved only the HTTP GET request to Core 0, overlooking that Wi-Fi scanning and association are also blocking calls. I moved all network operations into a dedicated Core 0 NetTask so loop() only reads volatile flags and never blocks.

원인 B — 리팩터링이 드러낸 순서 의존성Cause B — A Hidden Ordering Dependency Exposed by Refactoring

// [BEFORE] 스크롤 좌표 갱신이 else 분기 안에만 있었다
if (!isOfflineMode) {
    drawOnlineScreen();        // ← 내부에서 getLocalTime() 실패 시 drawOfflineScreen()으로 폴백
} else {
    if (now - lastScrollTime >= scrollSpeedMs) { offlineScrollX--; ... }   // ← 여기에만 존재
    drawOfflineScreen();
}

// [BEFORE] Scroll coordinate update lived only inside the else branch
if (!isOfflineMode) {
    drawOnlineScreen();        // ← Falls back to drawOfflineScreen() internally if getLocalTime() fails
} else {
    if (now - lastScrollTime >= scrollSpeedMs) { offlineScrollX--; ... }   // ← Only updated here
    drawOfflineScreen();
}

configTime() 은 비동기라 호출 직후에는 시계가 아직 무효다. NetTask 가 연결에 성공해 isOfflineMode = false 가 되면 drawOnlineScreen() 이 호출되지만, 시계가 없어 내부에서 오프라인 화면으로 폴백한다.

configTime() is asynchronous, so right after it is called, system time is not valid yet. Once NetTask connected and set isOfflineMode = false, loop() called drawOnlineScreen(), which saw invalid time and fell back to drawOfflineScreen() internally.

이때 offlineScrollX 는 else 분기에 있어 절대 갱신되지 않으므로 같은 프레임이 계속 그려진다 = 정지. UDP 123이 막혀 있거나 전파가 약해 SNTP가 끝내 동기화되지 않으면 영구 정지한다.

Because offlineScrollX was only decremented inside the else branch, the fallback path redrew the exact same scroll offset every frame—looking completely frozen. If UDP port 123 was blocked or weak signal prevented SNTP sync, the display stayed frozen forever.

• advanceOfflineScroll() — 스크롤 좌표 갱신을 분기 밖으로 옮겨, 어떤 화면을 그리든 항상 진행하게 했다.
• timeValid 상태 도입 — 온라인 화면은 연결됨 && 시계 유효일 때만 렌더링한다.
• ntpWatchdog() — 동기화 성공 시 플래그를 세우고, 60초 이상 미동기화면 configTime() 을 재요청한다.

• advanceOfflineScroll() — Moved scroll coordinate updates outside the if/else branch so the marquee advances regardless of which screen is active.
• Added timeValid state — The online screen renders only when both Wi-Fi is connected AND system time has synchronized.
• ntpWatchdog() — Sets timeValid once SNTP succeeds and re-triggers configTime() if time remains unsynchronized for over 60 seconds.

같이 잡은 것들Additional Fixes Along the Way

3편에서 "해결"이라고 적었던 판단 중 세 개가 여기서 뒤집혔다. 모뎀 슬립, 인증 실패 영구 고정, 그리고 잔상 퍼지. 구성이 바뀌자 당시의 판단이 오히려 발목을 잡았다.

Three of the four decisions I called "solutions" in Part 3 were reversed here: modem sleep, permanent offline lock on auth failure, and the horizontal purge sweep. Once the hardware setup changed, those earlier workarounds became liabilities.

현장에 걸기 전에 — 전파를 화면으로 보기Before Mounting on Site — Visualizing RF Signal on the Panel

공장 현장은 금속 케이스 내부 설치가 예정돼 있어 RF 차폐가 우려됐다. 그런데 설치 환경에서는 PC를 붙이기 어렵고, PSU 5V가 인가된 상태에서 USB를 꽂으면 역전류 위험이 있어 시리얼 모니터에 의존할 수 없었다.

At the factory site, the signboard was scheduled to be mounted inside a metal enclosure, raising concerns about RF shielding. Bringing a laptop up to the mounting location was impractical, and plugging USB into the board while the external 5V PSU was live risked back-feeding current, ruling out the Serial Monitor.

그래서 전파 세기를 LED 화면 자체에 표시하도록 만들었다.

So I built an on-screen RSSI diagnostic tool directly on the LED matrix.

버튼 극성은 부팅 시 실측해 자동 판별하므로 보드 리비전 차이를 코드 수정 없이 흡수한다.

Button active polarity is sampled automatically at boot, absorbing board revision differences without code changes.

실측해 보니 자세가 전부였다Field Measurements Showed Orientation Was Everything

• 설치 원칙 ① 모듈 안테나부가 패널 반대쪽·AP 방향을 향하게 배치한다.
• 설치 원칙 ② 어떤 벽면이든 20~30mm 이상 이격한다. 비용 0원으로 10dB 이상 확보할 수 있다.
• 공장은 거리 증가(2배마다 −6dB), 철골·철제 랙, 2.4GHz 간섭, 지게차에 의한 멀티패스 페이딩으로 마진이 깎인다. 현장 목표치는 임계값(−75)이 아니라 −65 이상으로 잡았다.

• Mounting Rule 1: Orient the controller board so its PCB antenna faces away from the LED panel ground plane and toward the AP.
• Mounting Rule 2: Maintain at least 20–30 mm clearance from any wall surface—recovering 10+ dB at zero hardware cost.
• Because factory floors add path loss, steel racks, 2.4 GHz noise, and multipath fading from moving forklifts, I set the on-site acceptance target at −65 dBm or better rather than the −75 dBm minimum threshold.

코드 정리Code Cleanup

• 매직넘버 전면 상수화 — GPIO 번호, 드라이브 강도, 드라이버 IC, i2s 속도, TX 파워, 절전 모드, 재시도 간격, RSSI 임계값, 게이지 좌표, 버튼 핀/디바운스까지 전부 constexpr 로 상단에 모았다.
• 하드코딩 좌표 제거 — 토스트 X좌표를 44/52로 고정하던 것을 문자열 길이 기반 자동 중앙정렬로 대체했다.
• 데드코드 제거 — NetTask 통합으로 불필요해진 별도 WeatherTask(태스크 생성/소멸 레이스 포함)와 write-only 변수를 정리했다.
• 진단 스위치 내장 — #define PANEL_DIAG_BLACK 1 로 렌더링을 전부 우회하고 PURE BLACK만 유지한다. 소프트웨어 원인 배제 여부를 1분 안에 판정할 수 있다.

• Replaced magic numbers with named constexpr constants — GPIO pins, drive strengths, driver IC type, I2S clock speed, TX power, sleep mode, retry intervals, RSSI thresholds, gauge coordinates, and button debounce timings are all consolidated at the top of the file.
• Removed hardcoded X offsets — Replaced fixed toast X coordinates (44/52) with automatic centering based on string length.
• Removed dead code — Deleted the obsolete WeatherTask (along with its task creation/destruction race condition) and unused write-only variables after unifying network jobs into NetTask.
• Built-in diagnostic switch — Setting #define PANEL_DIAG_BLACK 1 bypasses all rendering and holds PURE BLACK, ruling software causes in or out within a minute.

이 시리즈에서 남은 것Takeaways from the Four-Part Series

네 편에 걸쳐 쓴 것을 한 줄씩 줄이면 이렇게 된다.

Summarizing the four parts into one line each:

• "증상을 없애는 것"과 "원인을 제거하는 것"은 다르다. 가로 스위핑은 화면상으로 정상 동작하는 것처럼 보였지만 원인을 덮고 있었을 뿐이고, 실제로는 설정 한 줄이 문제였다.
• 교차 검증만이 원인을 확정한다. 후보가 여러 개일 때 한꺼번에 고치면 무엇이 효과가 있었는지 영영 알 수 없다. 변수를 하나씩 되돌려 재현 여부를 확인하는 절차가 유일하게 신뢰할 수 있는 방법이었다.
• 라이브러리는 문서가 아니라 소스로 확인한다. ICN2038S 옵션이 내부적으로 fm6124init() 으로 분기한다는 사실은 소스를 직접 읽고 나서야 알 수 있었다.
• 리팩터링은 숨어 있던 의존성을 드러낸다. 블로킹 대기를 없애자 그 대기에 기대고 있던 순서 문제가 표면으로 올라왔다.
• 현장 제약이 기능 요구사항을 만든다. 역전류 위험으로 시리얼을 못 쓴다는 제약이 없었다면 온스크린 RSSI 모니터와 버튼 진단 기능은 만들지 않았을 것이다.

• Masking a symptom is not the same as removing the cause. The horizontal sweep looked clean on screen, but it only painted over a misconfigured driver register.
• Only single-variable isolation confirms a root cause. Changing multiple parameters at once makes it impossible to know which change actually fixed the bug.
• Verify libraries by reading their source code, not just their docs. Only inspecting the library source revealed that ICN2038S branched into fm6124init().
• Refactoring exposes hidden temporal dependencies. Removing the blocking NTP wait in setup() surfaced a rendering branch bug that had relied on that delay.
• Field constraints shape better diagnostics. Without the back-current hazard preventing USB serial debugging on site, I would not have built the on-screen RSSI monitor and button reset tools.

이 유형의 실수(라이브러리 옵션이 실제로 무엇을 하는지 확인하지 않은 것, 핀 매핑을 가정으로 둔 것, 증상만 덮는 우회책)는 표로 정리해 프로젝트 문서에 남겼다. 다음에 같은 자리에서 시간을 쓰지 않기 위해서다.

I documented these failure patterns—assuming what a library enum does without reading the source, assuming pin mappings without checking the schematic, and mistaking visual workarounds for root-cause fixes—in the project notes so I don't pay the same tuition twice.