Skip to content

API.md

Latest commit

 

History

History
136 lines (96 loc) · 3.77 KB

API.md

File metadata and controls

136 lines (96 loc) · 3.77 KB

AsyncFsWebServer – API (overview)

This page summarizes the main methods exposed by AsyncFsWebServer and when to use them.

Note: some APIs are available only when the related features are enabled via macros (e.g. ESP_FS_WS_SETUP, ESP_FS_WS_EDIT).

Constructor

AsyncFsWebServer(uint16_t port, fs::FS &fs, const char* hostname = "");
  • port: HTTP port (typically 80)
  • fs: filesystem (LittleFS, SPIFFS, FFat, …)
  • hostname: optional (also used for mDNS)

Server start

bool init(AwsEventHandler wsHandle = nullptr);
  • Registers built-in handlers (setup/edit if enabled), static file serving, and notFound.
  • If wsHandle != nullptr, creates (or reuses) a websocket on /ws.

Runtime info

IPAddress getServerIP();
bool isAccessPointMode() const;

Authentication (/setup page)

void setAuthentication(const char* user, const char* pswd);

When set, the /setup page requires basic-auth.

Filesystem listing

void printFileList(fs::FS &fs, const char * dirname, uint8_t levels);
void printFileList(fs::FS &fs, const char * dirname, uint8_t levels, Print& out);
  • The Print& out overload lets you send output to streams other than Serial.

Example:

server.printFileList(FILESYSTEM, "/", 1);           // default -> Serial
server.printFileList(FILESYSTEM, "/", 1, Serial);  // explicit

WiFi + captive portal

bool startWiFi(uint32_t timeout, CallbackF fn = nullptr);
bool startCaptivePortal(const char* ssid, const char* pass, const char* redirectTargetURL);
  • startWiFi() tries to connect using already-saved credentials.
  • If it fails, you typically start startCaptivePortal() and use /setup to configure.

WebSocket (runtime)

AsyncWebSocket* getWebSocket();
void enableWebSocket(const char* path, AwsEventHandler handler);
void wsBroadcast(const char * buffer);
void wsBroadcastBinary(uint8_t * message, size_t len);

Setup page (only if ESP_FS_WS_SETUP)

Config file and callback:

File getConfigFile(const char* mode);
const char* getConfiFileName();
bool clearConfigFile();
void setConfigSavedCallback(ConfigSavedCallbackF callback);

Options and setup UI:

void setSetupPageTitle(const char* title);
void addOptionBox(const char* title);

// attach a comment string to an existing option element
// For most controls the comment is rendered in a separate line under the input.
// Boolean (checkbox) fields use a <span> so the text stays on the same line.
void addComment(const char *lbl, const char *comment);

// convenience overload: add an option and comment in one call
// bool-specific version avoids confusion with the templated overload
void addOption(const char *lbl, bool val, const char *comment, bool hidden = false, bool grouped = true);

// templated variant for other types
// note: bools are excluded via SFINAE
template <typename T, typename std::enable_if<!std::is_same<T, bool>::value, int>::type = 0>
void addOption(const char *lbl, T val, const char *comment);

template <typename T>
void addOption(const char *lbl, T val, bool hidden=false, double min=MIN_F, double max=MAX_F, double st=1.0);

template <typename T>
bool getOptionValue(const char *lbl, T &var);

template <typename T>
bool saveOptionValue(const char *lbl, T val);

Dropdown/Slider:

using DropdownList = AsyncFSWebServer::DropdownList;
using Slider = AsyncFSWebServer::Slider;

void addDropdownList(DropdownList &def);
void addSlider(Slider &def);
bool getDropdownSelection(DropdownList &def);
bool getSliderValue(Slider &def);

Web file editor (only if ESP_FS_WS_EDIT)

void enableFsCodeEditor(FsInfoCallbackF fsCallback = nullptr);
void setFsInfoCallback(FsInfoCallbackF fsCallback);

See also: SetupAndWiFi.md, FileEditorAndFS.md, WebSocket.md.