디바이스 설정¶

ESP32-S3 펌웨어는 두 가지 종류의 설정값을 가진다.

설정	저장 위치	변경 방법
Role / Index / Rate / Gateway / LAN	DIP 스위치 (실시간)	DIP 스위치 설정
MQTT / WiFi(OTA) / OTA URL / 모드	NVS (재부팅 후 유지)	SETUP 포털, UART 메뉴, UART 명령 — 아래

NVS 항목 변경에는 두 가지 방법이 있고, 모두 같은 저장소를 공유한다. 어느 방법으로 변경해도 다른 방법에서 동일한 값을 본다.

1. SETUP 포털 (Wi-Fi AP + 웹 폼)¶

가장 시각적이고 친숙한 방법. 폰/노트북 브라우저로 폼을 채워 저장한다.

진입¶

본체 IO35 버튼을 누른 채 전원 인가 (200 ms 이상 유지)

📷 [이미지 자리] 보드의 IO35 버튼 위치 표시 (사진에 빨간 화살표). 파일명: assets/board_io35_button.png

진입하면 OLED에 SSID / 비번 / URL 표시:

SETUP
WiFi: UWB-Anchor-XXXX
PW:   00000000
URL:  http://192.168.4.1

XXXX 는 MAC 주소 마지막 두 바이트로 디바이스마다 다르다.

설정¶

폰 Wi-Fi에서 UWB-Anchor-XXXX 접속, 비밀번호 00000000
브라우저에서 http://192.168.4.1 접속
폼 작성 후 Save & Reboot

페이지 상단 Current settings 박스에 현재 저장된 값이 표시되고, 아래 입력란에 새 값을 채우는 구조다.

📷 [이미지 자리] 폰 브라우저에서 본 SETUP 페이지 전체 캡처. Current settings 박스 + 입력 필드들이 보이는 모습. 파일명: assets/setup_portal_phone.png

입력 항목¶

그룹	필드	설명
MQTT	Host	브로커 주소
	Port	기본 1883
	User / Password	익명 접속이면 비워둠
	Topic prefix	실제 토픽은 `<prefix>/<role><idx>` 형태가 됨
Firmware Update	WiFi SSID / Password	OTA 다운로드 시 일시적으로 STA로 전환할 때 사용
	OTA URL	`firmware.bin` 의 직접 URL
	Update mode	`Manual` 또는 `Auto` (아래 OTA 섹션 참조)
	Force update	체크 시 버전 비교 없이 무조건 다시 받기

버튼¶

Save & Reboot — NVS 저장 후 재부팅
Save & Update Now — 저장 후 즉시 OTA 실행. AP가 잠시 꺼지고 STA로 전환되어 firmware.bin 다운로드 → 자동 재부팅

Wi-Fi 자격증명은 LAN(이더넷)이 연결되어 있어도 반드시 입력해야 한다. OTA는 GitHub Releases (HTTPS)에서 받는데 ENC28J60 LAN 스택은 TLS를 지원하지 않기 때문에 다운로드는 Wi-Fi 경로로만 가능하다.

2. UART 인터랙티브 메뉴¶

USB 시리얼 터미널에서 키보드로 메뉴 선택해 설정. 화면 깜빡임 없이 깔끔하게 진행된다.

진입¶

빈 줄에서 Enter 두 번 누름.

[Enter][Enter]

=== entering SETUP menu ===
Tips:
  - Pick an option by typing its number then Enter.
  - Inside a value prompt, just press Enter to keep
    current; type '-' to clear; Ctrl+C to cancel.
  - Changes are pending until you choose Save (5).

=== SETUP MENU ===           [Pending: 0]
1) MQTT
2) WiFi (for OTA)
3) OTA
4) Show all
5) Save & exit
6) Cancel & exit
0) Run OTA now (uses live cfg)
(Ctrl+C = cancel & exit menu)
> _

동작 방식¶

메뉴 안에서는 UWB 데이터 출력, DIP dump, STM32 패스스루가 일시 정지되어 화면이 깨끗하다 (MQTT publish는 계속됨)
변경은 pending 사본에 저장됨. NVS는 Save (5) 를 눌러야 기록됨
Cancel (6) 또는 메인 메뉴에서 Ctrl+C 누르면 변경 폐기

값 입력 규칙¶

각 항목 선택 시:

Editing: mqtt.user
Current value: admin
How to respond:
  - type new value then press Enter
  - press Enter alone to keep current
  - type '-' then Enter to clear (empty)
  - press Ctrl+C to cancel without changing
> _

입력	결과
`값` Enter	pending에 새 값 저장
Enter 단독	현재 값 유지 (변경 안 함)
`-` Enter	빈 값으로 클리어
Ctrl+C	입력 폐기, 직전 메뉴로
잘못된 값 (port 범위 초과, mode 오타 등)	에러 후 같은 프롬프트 재표시

Ctrl+C 동작 정리¶

위치	Ctrl+C 누르면
값 입력 중	입력 폐기, 직전 서브메뉴로
서브메뉴(MQTT/WiFi/OTA)	메인 메뉴로
메인 메뉴	메뉴 종료 (Cancel과 동일)

pio device monitor 의 기본 종료 키도 Ctrl+C이므로 메뉴 안에서 Ctrl+C를 디바이스로 전달하려면 모니터 종료 키를 옮겨 띄워야 한다:
pio device monitor -b 115200 --exit-char 29
이렇게 하면 Ctrl+] 가 모니터 종료 키가 되고, Ctrl+C는 디바이스로 전달된다. PuTTY/Tera Term은 기본적으로 Ctrl+C를 그대로 전달하므로 추가 설정 없이 동작한다.

3. OTA 펌웨어 업데이트¶

WiFi STA로 일시 전환해 firmware.bin 을 HTTPS로 받아 적용한다. 디바이스에 OTA URL과 WiFi 자격증명이 저장되어 있어야 한다.

Update mode¶

모드	동작
`manual`	부팅 시 OTA 안 함. SETUP의 Save & Update Now, 또는 UART 메뉴의 0) Run OTA now 로만 실행
`auto`	매 부팅 시 28-byte 사이드카(`firmware.version`) 받아 펌웨어의 `FW_VERSION` 과 비교, 다르면 다운로드

검증 안 된 펌웨어 위험을 줄이려면 처음에는 manual 권장. 검증 후 auto 로 전환.

시리얼 로그 예시¶

성공:

[ota] wifi connecting to home-wifi
[ota] wifi up, ip=192.168.0.123
[ota] remote="1.0.3" local="1.0.2"
[ota] downloading <URL>
ota: download
... 진행률 ...
[자동 재부팅 후 새 펌웨어 부팅]

같은 버전 (auto 모드, 변화 없을 때):

[ota] remote="1.0.2" local="1.0.2"
[ota] result: up-to-date

트러블슈팅¶

증상	원인
`wifi fail`	SSID/PW 오타, AP 신호 약함, 5 GHz 전용 AP (ESP32는 2.4 GHz만)
`version fetch http=4xx`	OTA URL 잘못, 또는 릴리스에 `firmware.version` 사이드카 누락
`fail: -2` 등	메모리 부족 또는 `.bin` 파일 손상
매 부팅마다 다운로드	`FW_VERSION` 과 사이드카가 안 맞음. 펌웨어 빌드 시 버전 주입 확인

4. IO35 버튼 동작 정리¶

동작	시점	결과
누른 채 전원 인가 (≥200 ms)	부팅 시	SETUP 포털 진입 (정상 부팅 차단)
5초 이상 홀드 후 떼기	평상시	소프트 재부팅
5초 미만 누름	평상시	무시

설치 후 OLED가 안 보이는 환경(천장 등)에서는 버튼이 안전망. 위치를 잊은 경우 Wi-Fi 스캔에서 UWB-Anchor-XXXX SSID가 보이면 SETUP 모드 진입에 성공한 것이다.

우선순위 / 충돌¶

DIP 스위치 (Role/Index 등) 와 NVS 항목은 독립적. 서로 영향 없음
같은 NVS 항목을 서로 다른 방법으로 변경했을 때 마지막 변경이 우선
SETUP 포털 안에서 OTA를 실행하면(메뉴 0번 또는 폼의 "Save & Update Now"), Wi-Fi 라디오가 AP에서 STA로 전환된 뒤 다운로드한다. AP는 그 시점에 끊긴다.