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 13a7562fa1 Added easyEDA source file 3 weeks ago
img ac9b46f3d5 auto update script executed 3 months ago
pcb 13a7562fa1 Added easyEDA source file 3 weeks ago
res ac9b46f3d5 auto update script executed 3 months ago
sd_card d62c615e32 Added blog engine 2 months ago
web-server ac9b46f3d5 auto update script executed 3 months ago
.gitignore ac9b46f3d5 auto update script executed 3 months ago
LICENSE 059d830470 Initial commit 3 months ago
README.md 2d7f9eef9b 更新 'README.md' 3 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)