A ESP12E/F powered web server with limited NAS functionality
A ESP12E/F powered web server with limited NAS functionality
@@ -5,20 +7,30 @@ A ESP12E/F powered web server with limited NAS functionality
## Features
## Features
- Basic Web Server
- Basic Web Server
+
- Directory View
- Directory View
+
- Cookie based login system
- Cookie based login system
+
- File Manager
- File Manager
+
- File Upload / Download (with multiple-file zip download support)
- File Upload / Download (with multiple-file zip download support)
- File Open, Cut and Copy
- File Open, Cut and Copy
- Support UTF-8 filename (32 bit length only, filename length depends on variable bytes used per char)
- Support UTF-8 filename (32 bit length only, filename length depends on variable bytes used per char)
+
- File Searching Tool
- File Searching Tool
+
- Much slower than Google Search (Is this even a feature?)
- Much slower than Google Search (Is this even a feature?)
+
- System Information
- System Information
+
- SD storage info
- SD storage info
- WiFi info
- WiFi info
+
- WebApps
- WebApps
+
- Music Player
- Music Player
- Photo Viewier
- Photo Viewier
- Video Player
- Video Player
@@ -138,8 +150,6 @@ As you might have notice by now this system is hosted on a 1 USD MCU (ESP8266),
- 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)
- 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)
-
-
## License
## License
Backend Code (Arduino): MIT License
Backend Code (Arduino): MIT License
@@ -147,5 +157,3 @@ Backend Code (Arduino): MIT License
Front-end Code (html files): CopyRight tobychui, All Right Reserved
Front-end Code (html files): CopyRight tobychui, All Right Reserved
*(I strongly recommend anyone with ability to write a better UI than my system :D)*
*(I strongly recommend anyone with ability to write a better UI than my system :D)*
+This is the template for the web-stick SD card contents. Copy and paste these files into your freshly formatted FAT32 micro SD card for the web-stick to operate normally.
+
+## Folder Structure
+
+The folder structure of the webstick contains three root folders.
+
+- /cfg -> Folder for storing configuration files
+
+- /www -> Folder for storing web files and contents (Except /www/store)
+
+- /db -> Key-value database folder, auto create when system startup
+
+#### Use as mp3 Streaming Site
+
+If you are planning to store your music collections in WebStick, you can catergorize your music by folder. AirMusic embedded player do not provide music auto sorting or catergory function based on file metadata. The playlist is automatically generated from the folder contents.
+
+#### Use as Tiny Cloud Storage
+
+Inside the /www folder, you can put any kind of folders except the special path /www/store is reserve for private file storage. If the file is accessed via web server interface (i.e. directly open your browser to http://webstick.local/store ), a 401 Error will be shown.
+
+To access the files inside /www/store, you can use the File Manager or file system API (/api/fs/download?file=/store/myfile.txt) if you are requesting such resources in your page.
+
+
+
+## Pre-installed WebApps
+
+There are a few pre-installed WebApps to get you started on your WebStick for your personal homepage with ease.
+
+- File Manager (ArozOS File Manager)
+
+- Markdown Editor (SimpleMDE)
+
+- Notepad (Ace-Editor)
+
+- Music Player (AirMusic)
+
+- Photo Viewer
+
+- Video Player (dPlayer)
+
+- Search Tool
+
+- System Info
+
+To start customizing your homepage, simply login to the admin panel and double click the html files in your root folder. You will be redirected to Notepad for realtime editing of your site.
+
+## Configurations
+
+#### WiFi Config
+
+To config wifi, put your wifi SSID and password into cfg/wifi.txt. The first line of the txt file is your wifi SSID and the 2nd line is the password. Make sure the new line is \n (Linux) instead of \r\n (Windows). Example as follows.
+
+```
+My Home WiFi
+12345678
+```
+
+#### Admin Account
+
+If you are using the API features, you can setup an admin account by creating a txt file named cfg/admin.txt, where the first line is the admin username and 2nd line is the password. Example as follows.
+
+```
+admin
+password
+```
+
+#### mDNS
+
+You can change the mDNS domain name by editing the mdns.txt file. By default, the name "webstick" is used and you can access your webstick using http://webstick.local if your browser support mDNS.
+
+
+
+## Developers
+
+### Backend API
+
+If you want to develop custom apps for WebStick, you can make use of the following APIs defined in server.ino file.
+Note that for POST paramter, please put them in the URL paramter (e.g. /api/fs/search?keyword=.mp3) instead of POST body, as ESP8266 do not have enough memory to parse the body.
+**Note that preference set require logged in user while preference get do not. So you can make use of this properties and use preference API for rendering on things like blog post or guest READ ONLY materials on your site.**
+
+### File Upload
+
+The endpoint /upload can be used to upload file using multipart FORM data. See /www/admin/upld.js for an example implementation, or you can directly include upld.js in your page and call to handleFile like the example below.
+
+```javascript
+const blob = new Blob(["Hello World!"], { type: 'text/plain' });
+const file = new File([blob], "hello.txt");
+handleFile(file, "/down/", function(){
+ alert("Upload done");
+});
+```
+
+The upload function also act as the "file write" function for the WebStick backend infrastructure.
+
+## Limitations
+
+The implementation already used AsyncTCP for best performance. Due to the limitation of hardware, the system have straight limitations on what file can be uploaded or downloaded.
+
+- Filepath must be 255 characters or less. Note that it is filepath length not filename, and UTF-8 characters will occupy from 1 - 4 bytes. By default, the backend limits the filename length to 32 chars (extension included)
+
+- Filesize of upload, although not limited, based on our testing, it is recommended to use files <= 5MB in size, including image, music or script files.
+
+- Use CDN if possible to reduce CPU load on the MCU
+
+
+
+## Too slow?
+
+This project is a trim-down version of the full feature [ArozOS](https://arozos.com) Open Source Project. If you want to host your own budget cloud system with even more features, visit [https://arozos.com](https://arozos.com) for more information.
+ <p>This web based text editor for ArOZ Online System are made possible by the ace editor, jQuery and ArOZ Project. Part of the system are licensed under BSD License. Please refer to the individual license information under the library folder. <br><br><br>
+ Developed for ArOZ Online Beta and migrated to ArozOS, trimmed down for WebStick project</p>
+ <hr>
+ <p>BSD License<p>
+ <p style="font-size:70%;">All rights reserved.
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+3. All advertising materials mentioning features or use of this software
+ must display the following acknowledgement:
+ This product includes software developed by the <organization>.
+4. Neither the name of the <organization> nor the
+ names of its contributors may be used to endorse or promote products
+ derived from this software without specific prior written permission.
+THIS SOFTWARE IS PROVIDED BY <COPYRIGHT HOLDER> ''AS IS'' AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
+ <div class="sub header" style="color: #adadad !important;">This function will recursively search the whole SD card using keyword matching algorithm.<br>
+ This might take a few minutes if you have a lots of files stored on your SD card.</div>
+ <div class="sub header" style="color: #adadad !important;">This search engine is only capable of filename keyword search and not fuzzy search. Make sure you only enter the critical keywords.</div>
+The store folder is a private storage folder which only allow admin access. You can upload files to this folder and use it as a tiny cloud storage. Due to the limitation on hardware, we do not recommend uploading file >5MB as this will take decades to upload and stream.
+ Serial.println("WiFi info is not set. Please create a file in the SD card named /cfg/wifi.txt with first line as WiFi SSID and 2nd line as Password");