SENSORS/ACTUATORS

INTERNET OF THING (IoT)

아두이노 나노 ESP32 - 이더넷

아두이노 나노 ESP32용 DIYables ESP32 WebApps 라이브러리 API 참조

개요

이 페이지는 Arduino Nano ESP32 보드에서 사용되는 DIYables ESP32 WebApps 라이브러리의 전체 API를 문서화합니다. 라이브러리는 모듈식 아키텍처를 따릅니다 — 각 웹 애플리케이션은 서버에 등록하는 독립형 클래스입니다. 프로젝트에 필요한 페이지 클래스만 포함하세요; 사용하지 않는 클래스는 플래시나 RAM을 소비하지 않습니다.

라이브러리는 WiFi 연결, HTTP 서빙, WebSocket 통신을 처리합니다. 스케치는 콜백과 전송 메서드를 통해 라이브러리와 상호작용합니다.

라이브러리 기능

모듈식 페이지 시스템: 필요한 앱만 등록; 각각은 독립적입니다
메모리 제어: 앱별 포함으로 플래시 및 RAM 사용량을 제어합니다
11개의 내장 웹 애플리케이션: 웹 프로그래밍 없이 즉시 사용 가능합니다
확장 가능한 기본 클래스: DIYablesWebAppPageBase에서 파생하여 커스텀 페이지를 구축합니다
WebSocket 우선 설계: 모든 실시간 데이터 교환은 포트 81의 WebSocket을 사용합니다
반응형 UI: 모든 내장 페이지는 데스크톱, 태블릿, 모바일에서 작동합니다
콜백 기반 API: 간단한 함수 등록 — 폴링이 필요 없습니다
동시 앱 지원: 하나의 서버에서 여러 페이지를 동시에 실행할 수 있습니다

핵심 클래스

DIYablesWebAppServer

중앙 서버 클래스. HTTP 라우팅, WebSocket 연결을 관리하고 수신 메시지를 올바른 등록 페이지 핸들러로 전달합니다.

생성자

DIYablesWebAppServer(int httpPort = 80, int websocketPort = 81)

지정된 포트 번호로 서버를 인스턴스화합니다.

httpPort: HTTP 요청용 포트 (기본값: 80)
websocketPort: WebSocket 연결용 포트 (기본값: 81)

연결 메서드

bool begin()

WiFi 또는 이더넷이 외부에서 이미 구성된 상태에서 서버를 시작합니다.

반환값: 성공 시 true, 실패 시 false

bool begin(const char* ssid, const char* password)

제공된 자격 증명으로 WiFi에 연결한 다음 HTTP 및 WebSocket 서버를 시작합니다.

ssid: 네트워크 이름
password: 네트워크 비밀번호
반환값: 성공 시 true, 실패 시 false

void loop()

보류 중인 HTTP 요청 및 WebSocket 이벤트를 처리합니다. loop() 내에서 매 반복마다 호출합니다.

bool isConnected()

보드에 활성 WiFi 연결이 있으면 true를 반환합니다.

String getIPAddress()

보드의 현재 IP 주소를 String으로 반환합니다.

페이지 등록

void addApp(DIYablesWebAppPageBase* app)

페이지 인스턴스를 서버에 등록합니다. 페이지의 URL 경로는 생성자에서 정의됩니다.

app: 페이지 객체에 대한 포인터

void removeApp(const String& path)

지정된 URL 경로의 페이지를 등록 해제합니다.

path: 경로 문자열 (예: "/chat")

DIYablesWebAppPageBase* getApp(const String& path)

지정된 경로의 등록된 페이지에 대한 포인터를 반환하거나, 찾지 못하면 nullptr을 반환합니다.

void setNotFoundPage(const DIYablesNotFoundPage& page)

요청이 등록된 페이지와 일치하지 않을 때 표시되는 커스텀 404 페이지를 할당합니다.

타입별 페이지 접근자

DIYablesWebDigitalPinsPage* getWebDigitalPinsPage()

등록된 디지털 핀 페이지를 반환하거나, 추가되지 않은 경우 nullptr을 반환합니다.

DIYablesWebSliderPage* getWebSliderPage()

등록된 슬라이더 페이지를 반환하거나, 추가되지 않은 경우 nullptr을 반환합니다.

DIYablesWebJoystickPage* getWebJoystickPage()

등록된 조이스틱 페이지를 반환하거나, 추가되지 않은 경우 nullptr을 반환합니다.

기본 클래스

DIYablesWebAppPageBase

모든 내장 및 커스텀 페이지 클래스가 확장하는 추상 기본 클래스. HTTP 응답 유틸리티, WebSocket 브로드캐스팅, 페이지 라이프사이클 훅을 제공합니다.

생성자

DIYablesWebAppPageBase(const String& pagePath)

지정된 URL 경로 아래에 페이지를 등록합니다.

pagePath: 이 페이지의 URL 경로 (예: "/web-joystick")

추상 메서드 — 커스텀 페이지에서 필수

virtual void handleHTTPRequest(IWebClient& client) = 0

브라우저가 HTTP를 통해 이 페이지를 요청할 때 호출됩니다.

client: HTTP 응답을 작성하기 위한 인터페이스

virtual void handleWebSocketMessage(IWebSocket& ws, const char* message, uint16_t length) = 0

WebSocket 메시지가 도착하고 그 접두사가 이 페이지와 일치할 때 호출됩니다.

ws: 메시지를 보낸 WebSocket 연결
message: 원시 메시지 내용
length: 메시지의 바이트 길이

virtual const char* getPageInfo() const = 0

시리얼 모니터 시작 출력에 표시되는 짧은 레이블 문자열을 반환합니다 (예: "🕹️ Web Joystick: ").

virtual String getNavigationInfo() const = 0

홈 페이지에서 이 페이지의 카드를 위한 HTML 조각을 반환합니다.

선택적 재정의 메서드

virtual void onWebSocketConnection(IWebSocket& ws)

새로운 WebSocket 클라이언트가 연결될 때 호출됩니다. 초기 상태를 보내기 위해 재정의합니다.

virtual void onWebSocketClose(IWebSocket& ws)

WebSocket 클라이언트가 연결을 끊을 때 호출됩니다.

유틸리티 메서드

const char* getPagePath() const

이 페이지의 등록된 URL 경로를 반환합니다.

bool isEnabled() const

이 페이지가 활성화되어 요청에 응답하면 true를 반환합니다.

void setEnabled(bool enable)

서버에서 제거하지 않고 페이지를 활성화하거나 비활성화합니다.

void sendHTTPHeader(IWebClient& client, const char* contentType = "text/html")

클라이언트에 표준 200 OK HTTP 헤더를 씁니다.

void sendWebSocketMessage(IWebSocket& ws, const char* message)

단일 WebSocket 연결에 메시지를 보냅니다.

void broadcastToAllClients(const char* message)

현재 연결된 모든 WebSocket 클라이언트에 메시지를 전달합니다.

void sendLargeHTML(IWebClient& client, const char* html)

청크 전송 인코딩을 사용하여 대용량 HTML 페이로드를 전송합니다.

커스텀 페이지 예제

class CustomPage : public DIYablesWebAppPageBase { public: CustomPage() : DIYablesWebAppPageBase("/custom") {} void handleHTTPRequest(IWebClient& client) override { sendHTTPHeader(client); client.println("<html><body>Custom Page</body></html>"); } void handleWebSocketMessage(IWebSocket& ws, const char* message, uint16_t length) override { sendWebSocketMessage(ws, "Response: " + String(message)); } const char* getPageInfo() const override { return " 🔧 Custom Page: "; } String getNavigationInfo() const override { return "<a href=\"/custom\" class=\"app-card custom\">" "<h3>🔧 Custom</h3><p>Custom functionality</p></a>"; } };

내장 페이지 클래스

DIYablesHomePage

모든 등록된 애플리케이션을 나열하는 탐색 허브.

생성자

DIYablesHomePage()

URL

---

DIYablesWebChatPage

브라우저와 보드 간의 양방향 텍스트 메시징.

생성자

DIYablesWebChatPage()

URL

/webchat

메서드

void onWebChatMessage(std::function<void(const String&)> callback)

브라우저가 채팅 메시지를 보낼 때마다 호출되는 핸들러를 등록합니다.

void sendToWebChat(const String& message)

보드에서 브라우저 채팅 뷰로 메시지를 전송합니다.

---

DIYablesWebMonitorPage

출력 로깅 및 명령 입력을 위한 브라우저 접근 가능한 시리얼 모니터.

생성자

DIYablesWebMonitorPage()

URL

/webmonitor

메서드

void onWebMonitorMessage(std::function<void(const String&)> callback)

브라우저가 명령을 보낼 때 호출되는 핸들러를 등록합니다.

void sendToWebMonitor(const String& message)

보드에서 브라우저 모니터로 로그 메시지를 전송합니다.

---

DIYablesWebDigitalPinsPage

디지털 핀 0–13을 읽고 쓰기 위한 웹 인터페이스.

생성자

DIYablesWebDigitalPinsPage()

URL

/webdigitalpins

메서드

void enablePin(int pin, int mode)

웹 인터페이스에서 핀을 표시하고 제어 가능하게 합니다.

pin: 핀 번호 (0–13)
mode: WEB_PIN_OUTPUT 또는 WEB_PIN_INPUT

void onPinWrite(std::function<void(int, int)> callback)

브라우저가 출력 핀을 토글할 때 호출되는 핸들러. (pin, state)를 받습니다.

void onPinRead(std::function<int(int)> callback)

브라우저가 입력 핀 상태를 요청할 때 호출되는 핸들러. 현재 상태를 반환합니다.

void onPinModeChange(std::function<void(int, int)> callback)

브라우저가 핀의 방향을 변경할 때 호출되는 핸들러.

void updatePinState(int pin, int state)

연결된 모든 브라우저 클라이언트에 업데이트된 핀 상태를 전송합니다.

---

DIYablesWebSliderPage

PWM 및 아날로그 제어에 적합한 이중 0–255 범위 슬라이더.

생성자

DIYablesWebSliderPage()

URL

/webslider

메서드

void onSliderValueFromWeb(std::function<void(int, int)> callback)

슬라이더가 움직일 때 호출되는 핸들러. 0–255 범위에서 (slider1, slider2)를 받습니다.

void onSliderValueToWeb(std::function<void()> callback)

새로 연결된 브라우저가 현재 슬라이더 위치를 요청할 때 호출되는 핸들러.

void sendToWebSlider(int slider1, int slider2)

슬라이더 값을 브라우저에 전송하여 표시된 위치를 업데이트합니다.

---

DIYablesWebJoystickPage

방향 제어를 위한 X/Y 좌표를 반환하는 2D 가상 조이스틱.

생성자

DIYablesWebJoystickPage(bool autoReturn = true, float sensitivity = 10.0)

autoReturn: true이면 조이스틱이 놓았을 때 중앙으로 돌아갑니다
sensitivity: 업데이트가 전송되기 전에 필요한 최소 이동 비율

URL

/webjoystick

메서드

void onJoystickValueFromWeb(std::function<void(int, int)> callback)

조이스틱 움직임 시 호출되는 핸들러. –100~+100 범위에서 각각 (x, y)를 받습니다.

void onJoystickValueToWeb(std::function<void()> callback)

브라우저가 현재 조이스틱 위치를 요청할 때 호출되는 핸들러.

void sendToWebJoystick(int x, int y)

연결된 브라우저에 현재 조이스틱 위치를 보냅니다.

void setAutoReturn(bool autoReturn)

런타임에 자동 중앙 복귀 동작을 업데이트합니다.

void setSensitivity(float sensitivity)

런타임에 움직임 감도 임계값을 업데이트합니다.

---

DIYablesWebPlotterPage

최대 8개의 동시 데이터 시리즈를 지원하는 스트리밍 데이터 플로터.

생성자

DIYablesWebPlotterPage()

URL

/webplotter

메서드

void setPlotTitle(const String& title)

플롯 위에 표시되는 차트 제목을 설정합니다.

void setAxisLabels(const String& xLabel, const String& yLabel)

X축과 Y축 레이블을 설정합니다.

void enableAutoScale(bool enable)

true이면 Y축 범위가 수신 데이터에 맞게 자동으로 조정됩니다.

void setMaxSamples(int maxSamples)

이전 포인트가 삭제되기 전에 시리즈당 유지되는 데이터 포인트 수를 제한합니다.

void addDataPoint(const String& seriesName, float x, float y)

명명된 시리즈에 단일 (x, y) 포인트를 추가합니다.

void clearPlot()

모든 시리즈에서 모든 데이터를 제거합니다.

---

DIYablesNotFoundPage

등록되지 않은 경로에 대해 표시되는 선택적 404 응답 페이지.

생성자

DIYablesNotFoundPage()

기본 사용법

다음 스케치는 Arduino Nano ESP32 프로젝트에 채팅 및 모니터 페이지를 추가하는 방법을 보여줍니다:

#include <DIYablesWebApps.h> const char* ssid = "YOUR_WIFI_SSID"; const char* password = "YOUR_WIFI_PASSWORD"; DIYablesWebAppServer webAppsServer(80, 81); DIYablesHomePage homePage; DIYablesWebChatPage chatPage; DIYablesWebMonitorPage monitorPage; void setup() { Serial.begin(9600); webAppsServer.addApp(&homePage); webAppsServer.addApp(&chatPage); webAppsServer.addApp(&monitorPage); webAppsServer.setNotFoundPage(DIYablesNotFoundPage()); if (webAppsServer.begin(ssid, password)) { Serial.println("Server started"); Serial.print("IP: "); Serial.println(webAppsServer.getIPAddress()); } chatPage.onWebChatMessage([](const String& message) { Serial.println("Chat received: " + message); chatPage.sendToWebChat("Board reply: " + message); }); } void loop() { webAppsServer.loop(); delay(10); }

웹 애플리케이션 URL 참조

Application	Default URL
Home Page	http	//[board-ip]/
Chat	http	//[board-ip]/webchat
Web Monitor	http	//[board-ip]/webmonitor
Digital Pins	http	//[board-ip]/webdigitalpins
Slider	http	//[board-ip]/webslider
Joystick	http	//[board-ip]/webjoystick
Plotter	http	//[board-ip]/webplotter

WebSocket 프로토콜

모든 실시간 통신은 포트 81의 단일 WebSocket 서버를 통해 이루어집니다.

WebSocket 엔드포인트: ws://[보드-IP]:81
재연결: 연결이 끊기면 브라우저가 자동으로 재연결합니다
메시지 형식: 텍스트 기반; 각 내장 앱은 고유한 접두사를 사용하여 메시지를 식별합니다

앱별 메시지 패턴

채팅 — 양방향 일반 텍스트

모니터 — 양방향 일반 텍스트

디지털 핀

브라우저 → 보드: {"pin": 13, "state": 1}
보드 → 브라우저: {"pin": 13, "state": 1}

슬라이더

브라우저 → 보드: {"slider1": 128, "slider2": 255}
보드 → 브라우저: {"slider1": 128, "slider2": 255}

조이스틱

브라우저 → 보드: {"x": 50, "y": -25}
보드 → 브라우저: {"x": 50, "y": -25}

플로터

브라우저 → 보드: 해당 없음 (표시 전용)
보드 → 브라우저: {"series": "temp", "x": 10.5, "y": 23.4}

메모리 참조

프로젝트에서 사용하는 페이지만 포함하세요. 구성 요소당 대략적인 풋프린트:

Component	Flash	RAM
DIYablesWebAppServer	~8 KB	~2 KB
DIYablesHomePage	~3 KB	~1 KB
DIYablesWebChatPage	~6 KB	~1.5 KB
DIYablesWebMonitorPage	~5 KB	~1.5 KB
DIYablesWebDigitalPinsPage	~8 KB	~2 KB
DIYablesWebSliderPage	~6 KB	~1.5 KB
DIYablesWebJoystickPage	~7 KB	~1.5 KB
DIYablesWebPlotterPage	~10 KB	~2 KB
WebSocket buffer (per client)	—	~1 KB

최소 프로젝트 (서버 + 홈 + 앱 하나): ~17 KB 플래시, ~4.5 KB RAM

모든 앱 활성화: ~53 KB 플래시, ~12 KB RAM