esp_wifi_repeater

완전한 기능을 갖춘 WiFi NAT 라우터 (그리고 이제는 WiFi 리피터, 즉 L2 브리지)

2026년 신규: 첫 출시 후 10년 만에 드디어 원래 의도했던 대로 진정한 WiFi 리피터가 되었습니다. 기존 문서와 링크를 깨지 않기 위해 표준 버전은 여전히 잘 알려진 고급 기능을 갖춘 NAT 라우터 버전으로 유지됩니다. 하지만 단순화된 진정한 L2 브리지에 관심이 있다면 아래 ESP8266 WiFi Repeater - L2 bridge 섹션을 참조하세요.

이것은 esp8266 및 esp8285에서 WiFi NAT 라우터를 구현한 것입니다. 패킷 필터링 방화벽(ACL 포함), 포트 매핑, 트래픽 쉐이핑, 원격 모니터링(또는 패킷 스니핑)을 위한 훅, MQTT 관리 인터페이스, 간단한 GPIO 상호작용 및 전원 관리를 지원합니다. 더 넓은 영역을 커버하기 위해 여러 라우터를 메시로 설정하는 새로운 모드 "Automesh"가 포함되었습니다.

NAT 기능을 Arduino 프로젝트에 통합하는 방법을 찾고 있다면 - 여기를 참조하세요.

EPS32 NAT Router는 ESP32를 위한 고급 프로젝트입니다.

일반적인 사용 시나리오는 다음과 같습니다:

• 기존 WiFi 네트워크용 간단한 범위 확장기
• 배터리로 구동되는 실외 (메시) 네트워크
• 손님을 위한 별도의 SSID/비밀번호를 가진 추가 WiFi 네트워크 설정
• IoT 기기를 위한 안전하고 제한된 네트워크 설정
• WPA2 Enterprise 네트워크를 WPA-PSK로 변환
• WiFi 트래픽 분석을 위한 모니터 프로브
• 경로, ACL 및 트래픽 쉐이핑을 이용한 네트워크 실험
• 기본 I/O 기능과 MQTT 제어가 가능한 메시 IoT 장치

기본적으로 ESP는 STA 및 soft-AP로 작동하며 모든 IP 트래픽을 투명하게 전달합니다. NAT를 사용하므로 네트워크 측이나 연결된 스테이션에 라우팅 항목이 필요하지 않습니다. 스테이션은 기본적으로 DHCP를 통해 192.168.4.0/24 네트워크에서 구성되며 기존 WiFi 네트워크에서 DNS 응답자 주소를 받습니다.

측정 결과 양방향으로 약 5Mbps를 달성할 수 있어 스트리밍도 가능합니다.

일부 세부 사항은 이 비디오에서 설명됩니다.

웹 설치 프로그램

기기에 직접 플래싱하려면 웹 설치 프로그램을 사용하세요.

첫 부팅

esp_wifi_repeater는 다음 기본 구성으로 시작됩니다:

• ap_ssid: MyAP, ap_password: 없음, ap_on: 1, ap_open: 1
• network: 192.168.4.0/24

첫 부팅(또는 공장 초기화) 후에는 SSID "MyAP"로 개방형 AP를 제공하는 WiFi 네트워크를 제공합니다. 아직 업링크 AP에 자동으로 재연결을 시도하지 않습니다(유효한 SSID 또는 비밀번호를 모르기 때문).

이 WiFi 네트워크에 연결하고 간단한 웹 인터페이스 또는 콘솔을 통한 모든 옵션이 포함된 전체 구성을 통해 기본 구성을 수행합니다.

기본 웹 구성 인터페이스

웹 인터페이스는 기본 전달 기능에 필요한 모든 매개변수를 구성할 수 있습니다. rubfi의 주요 작업에 감사드립니다: https://github.com/rubfi/esp_wifi_repeater/ . 브라우저를 "http://192.168.4.1"로 지정하세요. 이 페이지가 나타납니다:

먼저 업링크 WiFi 네트워크에 적합한 값인 "STA 설정"을 입력하세요. 개방형 네트워크의 경우 비밀번호 "none"을 사용하세요. 실제로 automesh 모드를 사용하려는 경우에만 "Automesh" 상자를 선택하세요. "Connect"를 클릭합니다. ESP가 재부팅되고 WiFi 라우터에 연결됩니다. 몇 초 후 상태 LED가 깜빡여야 합니다.

automesh를 선택했다면 구성이 완료된 것입니다. automesh 모드에서는 이러한 설정이 "STA 설정"과 동일하므로 "Soft AP 설정"을 구성할 필요가 없습니다. 모든 연결된 ESP 리피터에서 동일한 SSID가 제공됩니다.

automesh를 사용하지 않는 경우, 이제 페이지를 다시 로드하고 "Soft AP 설정"을 변경할 수 있습니다. "Set"을 클릭하면 ESP가 다시 재부팅됩니다. 이제 새로 구성된 Soft AP를 통해 트래픽을 전달할 준비가 되었습니다. 이러한 변경 사항은 구성 인터페이스에도 영향을 미치므로 추가 구성을 위해 새로 구성된 WiFi 네트워크 중 하나를 통해 ESP에 연결하세요. Soft AP를 통한 액세스의 경우 Soft AP 네트워크의 주소가 변경된 경우 기억하세요(이 네트워크에서 ESP는 항상 x.x.x.1 주소를 가집니다).

원한다면 "lock" 확인란을 표시하고 "Lock"을 클릭할 수 있습니다. 그러면 업링크 WiFi 네트워크의 비밀번호로 잠금 해제하지 않고는 구성을 변경할 수 없습니다(네트워크가 개방형이더라도 비밀번호를 하나 정의하세요).

웹 인터페이스에 ASCII가 아니거나 특수 문자를 입력하려면 "My%20AccessPoint"와 같은 HTTP 스타일 16진수 인코딩을 사용해야 합니다. 그러면 문자열 "My AccessPoint"가 생성됩니다. 이 16진수 인코딩을 사용하면 0을 제외한 모든 바이트 값을 입력할 수 있습니다(C 내부 이유).

실수로 ESP와의 모든 접촉을 잃었다면 직렬 콘솔을 사용하여 복구할 수 있습니다("reset factory", 아래 참조).

명령줄 인터페이스

고급 구성은 콘솔 인터페이스의 명령줄을 통해 수행해야 합니다. 이 콘솔은 직렬 포트(115200 보드) 또는 tcp 포트 7777(예: 연결된 STA에서 "telnet 192.168.4.1 7777")을 통해 사용할 수 있습니다.

초기 설정에는 다음 명령을 사용하세요:

• set ssid your_home_router's_SSID
• set password your_home_router's_password
• set ap_ssid ESP's_ssid
• set ap_password ESP's_password
• show (매개변수 확인용)
• save
• reset

다시 말하지만, ASCII가 아니거나 특수 문자를 입력하려면 HTTP 스타일 16진수 인코딩(예: "My%20AccessPoint")을 사용하거나 CLI에서만 단축키로 C 스타일 따옴표와 백슬래시(예: "My\ AccessPoint")를 사용할 수 있습니다. 두 방법 모두 문자열 "My AccessPoint"를 생성합니다.

명령줄은 훨씬 더 많은 명령을 이해합니다:

기본 명령

거의 모든 환경에서 작동하도록 하기에 충분합니다.

• help: 간단한 도움말 메시지 출력
• set [ssid|password] value: 업링크 AP(홈 라우터의 WiFi 구성) 설정 변경, 개방형 네트워크의 경우 비밀번호 "none" 사용.
• set [ap_ssid|ap_password] value: ESP의 soft-AP(스테이션용) 설정 변경
• show [config|stats]: 현재 구성 또는 상태 정보 및 통계 출력
• save [dhcp]: 현재 구성 매개변수, ACL 및 라우팅 항목 [+ 현재 DHCP 임대]를 플래시에 저장
• lock [password]: 현재 구성을 저장하고 잠금, 변경 허용 안 함. 비밀번호는 이전에 설정된 경우 생략 가능(기본값은 업링크 WiFi의 비밀번호)
• unlock password: 구성 잠금 해제, lock 명령의 비밀번호 필요
• reset [factory]: ESP 재설정, 'factory'는 선택적으로 WiFi 매개변수를 기본값으로 재설정(잠금 장치에서는 직렬 콘솔에서만 작동)
• quit: 원격 세션 종료

고급 명령

대부분의 set 명령은 save와 reset 후에 적용됩니다.

명령줄 입력에서 단일 "#" 뒤의 모든 내용은 줄 끝까지 주석으로 처리되어 무시됩니다.

Automesh 구성

• set automesh [0|1]: automesh 모드 켜기/끄기 선택(기본값 꺼짐), 자세한 내용은 여기 https://github.com/martin-ger/esp_wifi_repeater#automesh-mode 참조
• set am_threshold dB: "나쁜" 연결에 대한 임계값 설정(음수 dB, 기본값 85, 즉 -85dB)
• set am_scan_time secs: automesh 모드에서 ESP가 업링크 AP를 찾기 위해 시도하는 시간 간격(초), 그 후 절전 모드 진입(0 비활성화, 기본값)
• set am_sleep_time secs: 업링크 AP를 찾지 못한 경우 automesh 모드에서 ESP가 절전하는 시간 간격(초) (0 비활성화, 기본값)

WiFi 구성

• set ap_on [0|1]: soft-AP 비활성화(ap_on=0) 또는 활성화(ap_on=1, 기본값) 선택
• set ap_open [0|1]: soft-AP가 WPA2-PSK 보안 사용(ap_open=0, ap_password 설정 시 자동) 또는 개방형(ap_open=1) 선택
• set auto_connect [0|1]: STA가 AP에 재연결을 계속 시도할지 여부 선택. auto_connect는 첫 플래싱 또는 "reset factory" 후 꺼짐(0). 새 SSID 입력 시 자동으로 켜짐(1).
• set ssid_hidden [0|1]: soft-AP의 SSID 숨김(ssid_hidden=1) 또는 표시(ssid_hidden=0, 기본값) 선택
• set phy_mode [1|2|3]: WiFi의 PHY_MODE 설정 (1=b, 2=g, 3=n(기본값))
• set country CC: WiFi 규제 국가 코드를 2자리 ISO 3166-1 코드(예: "US", "DE", "CN", "JP")로 설정. 미국 이외 코드는 채널 12와 13을 잠금 해제합니다. 비어 있음(기본값)은 SDK 기본값을 변경하지 않습니다. 설정은 플래시에 저장되고 부팅 시마다 다시 적용됩니다.
• set bssid xx:xx:xx:xx:xx:xx: 연결할 업링크 AP의 특정 BSSID 설정 (기본값 00:00:00:00:00:00은 모든 AP 허용)
• set [ap_mac|sta_mac] xx:xx:xx:xx:xx:xx: STA 및 SOFTAP의 MAC 주소를 사용자 정의 값으로 설정 (MAC 주소 첫 번째 바이트의 비트 0은 1이 될 수 없음)
• set sta_mac random: 재부팅 후 매번 새로운 랜덤 STA MAC 설정
• set sta_hostname name: STA의 이름 설정 (업링크 AP에 표시됨)
• set max_clients [1-8]: SoftAP에 연결할 수 있는 STA 수 설정 (ESP의 SoftAP 구현 한도는 8, 기본값)
• scan: AP 스캔 수행
• connect: 현재 구성된 ssid 및 _password_로 AP에 연결 시도
• disconnect: 업링크 AP에서 연결 해제

WPA2 Enterprise 구성

• set use_peap[0|1]: STA가 일반 WPA-PSK(use_peap=0, 기본값) 또는 WPA2 Enterprise(PEAP)를 사용하여 연결할지 선택
• set peap_identity value: PEAP '외부' ID 설정 (RADIUS 서버에 처음 제시되는 문자열, 예: [email protected])
• peap_username value: PEAP 사용자 이름 설정
• peap_password value: PEAP 비밀번호 설정

TCP/IP 구성

• set network ip-addr: 내부 네트워크의 IP 주소 설정, 네트워크는 항상 /24, 라우터는 항상 x.x.x.1
• set dns dns-addr: DHCP를 통해 클라이언트에 배포할 정적 DNS 주소 설정
• set dns dhcp: DHCP의 동적 DNS 주소 사용 구성, 기본값
• set ip ip-addr: STA 인터페이스의 정적 IP 주소 설정
• set ip dhcp: STA 인터페이스의 동적 IP 주소 구성, 기본값
• set netmask netmask: STA 인터페이스의 정적 넷마스크 설정
• set gw gw-addr: STA 인터페이스의 정적 게이트웨이 주소 설정
• set max_nat no_of_entries: NAPT 테이블 크기 설정 (기본값 512)
• set max_portmap no_of_entries: 포트맵 테이블 크기 설정 (기본값 32)
• set tcp_timeout secs: TCP 연결의 NAPT 타임아웃 설정 (0=기본값 (1800초))
• set udp_timeout secs: UDP 연결의 NAPT 타임아웃 설정 (0=기본값 (2초))
• set lease min: 내부 네트워크 DHCP 서버의 임대 시간 설정(분) (기본값 120)
• show dhcp: 현재 DHCP 임대 테이블 상태 출력

라우팅

• show route: 현재 라우팅 테이블 표시
• route clear: 모든 정적 라우트 제거
• route add network gw: 게이트웨이 gw를 통해 네트워크에 정적 라우트 추가 (네트워크는 CIDR 표기법('x.x.x.x/n')으로 제공)
• route delete network: 네트워크에 대한 정적 라우트 제거
• interface inX [up|down]: 인터페이스 상태를 up 또는 down으로 설정 (down 인터페이스를 통한 IP 라우팅/트래픽 없음, 기본값: up)
• set nat [0|1]: soft-AP 인터페이스가 NAT 처리(nat=1, 기본값)되는지 여부(nat=0) 선택. NAT 없이 내부 STA의 트래픽 투명 전달이 작동하지 않습니다! 주로 정적 라우팅과 조합하여 유용합니다.
• portmap add [TCP|UDP] external_port internal_ip internal_port: 포트 포워딩 추가
• portmap remove [TCP|UDP] external_port: 포트 포워딩 삭제
• nslookup name: 주어진 이름에 대한 DNS 조회를 시작하고 결과 표시
• ping host: ICMP 에코 요청/응답으로 IP 연결 확인 (호스트는 IP 주소 또는 DNS 이름)