A ESP12F powered, USB stick form factor ready to use Web Server that provide minimal function to a personal NAS system or web server

Toby Chui 4265291efb Updated fs.html to fix undefine bug 3 months ago
firmware fd7b0e47b3 optimized user UI 3 months ago
img ac9b46f3d5 auto update script executed 10 months ago
pcb 9677fd4a95 added v3 3 months ago
res ac9b46f3d5 auto update script executed 10 months ago
sd_card 4265291efb Updated fs.html to fix undefine bug 3 months ago
web-server ac9b46f3d5 auto update script executed 10 months ago
.gitignore ac9b46f3d5 auto update script executed 10 months ago
LICENSE 059d830470 Initial commit 10 months ago
README.md 2d7f9eef9b 更新 'README.md' 10 months ago



A ESP12E/F powered web server with limited NAS functionality


  • Basic Web Server

  • Directory View

  • Cookie based login system

  • File Manager

    • File Upload / Download (with multiple-file zip download support)

    • File Open, Cut and Copy

    • Support UTF-8 filename (32 bit length only, filename length depends on variable bytes used per char)

  • File Searching Tool

    • Much slower than Google Search (Is this even a feature?)
  • System Information

    • SD storage info
    • WiFi info
  • WebApps

    • Music Player
    • Photo Viewier
    • Video Player
    • Markdown Editor
    • Notepad (Modified version of ACE Editor)



  1. Format your micro SD card as FAT (Recommend using SD Card Formatter)
  2. Download and put everything under sd_card folder in this repo into your micro SD card
  3. Edit the files under /cfg/ to setup WiFi credentials (wifi.txt), management passwords (admin.txt) and optionally mDNS domain name (mdns.txt)
  4. Insert your SD card into the WebStick SD card slot
  5. Power on your WebStick by inserting it into your computer USB port (for debug / flash mode) or phone charger with USB A port.
  6. Access your WebStick using the device IP address ( or mDNS name (e.g. http://webstick.local)

Using your domain with WebStick

mDNS are local only domain names. If you want your viewer to be able to access your website from the public internet via your domain or your home public ip address, you will need to purchase a domain name, setup your DNS and / or your NAT router's port forward rules.

Build from Source

The following libraries are required for building the WebStick backend code (firmware to be used in ESP8266) using Arduino IDE. You can find the source code for the backend bare metal web-server in the /web-server folder.

Board Settings

Here are the recommended settings for best performance.

  • Board: Wemos D1 R2 & Mini

    • CPU clockspeed: 160Mhz

    • IwIP Varient: v2 Higher Bandwidth

Require external library:


Basic Web Servers

The WebStick provide basic web server functions like a fresh install Apache


▲ Homepage template


▲ Web server for HTML files


▲ Directory listing

Admin / Management Functions

WebStick contains basic functions for single admin environment. All file operations can only be performed by the only admin user in this system.


▲ Login / User System (based on Cookie not Basic Auth)


▲File Manager (Support upload, (multi-zip) download, copy, cut, paste, rename and new folder / files)


▲ Basic Search Engine (for local files)


▲ System Statistics


There are also limited multimedia streaming functionality on the WebStick.


▲ Basic Music Player


▲ Video Player (really small webm / mp4 files only)


▲ Photo Viewer

Other Utilities

WebStick also got other text editing utilities. If you are using markdown as notes or you want to update your website remotely, you can use the markdown editor or the notepadA editor.


▲ Markdown Editor (Powered by SimpleMDE project)


▲ NotepadA Code Editor (Powered by ace editor, support multi-tabs)


As you might have notice by now this system is hosted on a 1 USD MCU (ESP8266), even if web server is written in bare metal, it still have the following limitations

  • Filename length (hardcoded to 32 bits per filename, might be shorter for UTF-8 as it use variable byte structure, but technically this is not the system limit)

  • File size limit (recommend) <= 5MB, any file size larger than 5MB that is not stream-able (e.g. mp4) is not meaningful. Stream-able files can be larger than this size (e.g. webm) with acceptable playback speed.

  • Slow Upload / Download speed (2 - 4Mbps), Very slow concurrent R/W speed (200 - 210 Kbps)

  • Single admin session (cookie), due to limit in runtime memory (i.e. If you try to login from 2nd browser, the first browser will automatically logged out)

Getting the Hardware

You can place order at PCB printing service provider like JLCPCB or get one from my Tindie Store


Hardware Design (PCB files): CC BY-NC-SA

Backend Code (Arduino): MIT License

Front-end Code (html files): AGPL

(I strongly recommend anyone with ability to write a better UI than my system :D)