|
| 1 | +# FSBrowser readme |
| 2 | + |
| 3 | +## What is this sketch about ? |
| 4 | + |
| 5 | +This example is a FileSystem Browser for the ESP8266 using http requests and a html/javascript frontend, |
| 6 | +working for all of SPIFFS, LittleFS and SDFS. |
| 7 | +This unified version is based on the previous examples named FSWebServer, FSBrowser and SDWebServer, Copyright (c) 2015 Hristo Gochkov. All rights reserved. |
| 8 | + |
| 9 | +## How to use it ? |
| 10 | +1. Uncomment one of the `#define USE_xxx` directives in the sketch |
| 11 | +2. Add the credentials of your WiFi network (search for `STASSID`) |
| 12 | +3. Compile and upload the sketch to your ESP8266 device |
| 13 | +4. For normal use, copy the contents of the `data` folder to the filesystem. To do so: |
| 14 | +- for SDFS, copy that contents (not the data folder itself, just its contents) to the root of a FAT/FAT32-formated SD card connected to the SPI port of the ESP8266 |
| 15 | +- for SPIFFS or LittleFS, please follow the instructions at https://arduino-esp8266.readthedocs.io/en/latest/filesystem.html#uploading-files-to-file-system |
| 16 | +5. Once the data and sketch have been uploaded, access the editor by pointing your browser to http://fsbrowser.local/edit |
| 17 | + |
| 18 | +## Options |
| 19 | +If you need to free some space on the ESP filesystem, you can delete all the sample files at the root but also replace the `index.htm` file in the `data/edit` subfolder by the `index.htm.gz` file from the `extras` folder. That compressed version is not suited for learning or debugging, but will bring the total FS usage under 7KB. |
| 20 | +If you want to use the browser on a an existing filesystem or don't want to perform step 4 above, you have two possibilities : |
| 21 | +- either upload the `index.htm` file to the filesystem by opening a command shell in the `data` folder and running the following cURL command: |
| 22 | +`curl -F file=@edit/index.htm;filename=/edit/index.htm fsbrowser.local/edit` |
| 23 | +- or embed a version of the html page in the source code itself by uncommenting the following line in the sketch and rebuilding: |
| 24 | +`#define INCLUDE_FALLBACK_INDEX_HTM` |
| 25 | +That embedded version is functionally equivalent and will be returned if no `/edit/index.htm` or `/edit/index.htm.gz` file can be found on the filesystem, at the expense of a higher binary size. |
| 26 | + |
| 27 | +If you use the gzipped or `INCLUDE_FALLBACK_INDEX_HTM` options, please remember to rerun the `reduce_index.sh` script located in the `extras` subfolder and recompile the sketch after each change to the `index.html` file. |
| 28 | + |
| 29 | +## Dependency |
| 30 | +The html page uses the [Ace.js](https://ace.c9.io/) (v1.4.9 at the time of writing) text editor which is loaded from a CDN. Consequently, internet access from your web browser is required for the FSBrowser editing feature to work as-is. |
| 31 | + |
| 32 | +If your browser has no web access (e.g. if you are connected to the ESP8266 as an access-point), you can copy the `ace.js` file to the `edit` subfolder of the ESP filesystem, along with optional plugins etc. according to your needs. A typical set might be: |
| 33 | +``` |
| 34 | +ace.js |
| 35 | +ext-keybinding_menu.js |
| 36 | +ext-searchbox.js |
| 37 | +mode-html.js |
| 38 | +worker-html.js |
| 39 | +worker-css.js |
| 40 | +worker-javascript.js |
| 41 | +mode-xml.js |
| 42 | +worker-xml.js |
| 43 | +mode-json.js |
| 44 | +worker-json.js |
| 45 | +``` |
| 46 | +(see https://github.com/ajaxorg/ace-builds for a full list). |
| 47 | + |
| 48 | +If `ace.js` cannot be found on the ESP filesystem either, the page will default to a plain text viewer, with a warning message. |
| 49 | + |
| 50 | +## Notes |
| 51 | +- See https://arduino-esp8266.readthedocs.io/en/latest/filesystem.html for more information on FileSystems supported by the ESP8266. |
| 52 | +- For SDFS, if your card's CS pin is not connected to the default pin (4), uncomment the `fileSystemConfig.setCSPin(chipSelectPin);` line, specifying the GPIO the CS pin is connected to |
| 53 | +- `index.htm` is the default index returned if your URL does not end with a filename (works on subfolders as well) |
| 54 | +- Filesystem limitations apply. For example, FAT16 is limited to 8.3 filenames - see https://en.wikipedia.org/wiki/8.3_filename - SPIFFS and LittleFS also have limitations, please see https://arduino-esp8266.readthedocs.io/en/latest/filesystem.html#spiffs-file-system-limitations |
| 55 | +- Directories are supported on SDFS and LittleFS. On SPIFFS, all files are at the root, although their names may contain the "/" character. |
| 56 | +- The convention here is that the root of the filesystem is "/". On SPIFFS, paths not started with a slash are not supported |
| 57 | +- For creation, the convention is that a path ending with a "/" means create a folder, while without a "/" we create a file. Having an extension or not does not matter. |
| 58 | + |
| 59 | +## Changelog since original FSBrowser |
| 60 | + |
| 61 | +### Fixes to work on LittleFS based on SDFS |
| 62 | +- #define logic to select FS |
| 63 | +- switched from SD to SDFS |
| 64 | +- begin() does not support parameters > removed SS and added optional config |
| 65 | +- LittleFS.open() second parametsr is mandatory > specified "r" where needed |
| 66 | +- 'FILE_WRITE' was not declared in this scope > replaced by "w" |
| 67 | + |
| 68 | +### UI/usability improvements |
| 69 | +- Never format filesystem, just return "FS INIT ERROR" when FS cannot be mounted |
| 70 | +- Tree panel width is now proportional (20%) to see long names on big screens |
| 71 | +- Added icons for files, and indented them to the same level as folders |
| 72 | +- Changed file/folder icon set to use a lighter and more neutral one, and added specific "text" and "image" icons for formats recognized as such |
| 73 | +- Items are now sorted (folders first, then plain files, each in alphabetic order) |
| 74 | +- Added file size after each file name |
| 75 | +- Added FS status information at the top right |
| 76 | +- Made clear that an async operation is in progress by dimming screen and showing operation status |
| 77 | +- Filled filename box in header with the name of the last clicked file |
| 78 | +- Selecting a file for upload defaults to putting it in the same folder as the last clicked file |
| 79 | +- Removed limitation to 8.3 lowercase filenames |
| 80 | +- Support Filenames without extension, Dirnames with extension |
| 81 | +- Improved recursive refresh of parts of the tree (e.g. refresh folder upon file delete, show last folder upon creating nested file) |
| 82 | +- Added Save/Discard/Help buttons to ACE editor, discard confirmation on leave, and refresh tree and status upon save |
| 83 | +- Removed "Upload" from context menu (which didn't work anyway) |
| 84 | +- Added "Rename/Move" feature to context menu |
| 85 | +- Sketch can be used on a preexisting filesystem by embedding the index.htm file in the program |
| 86 | + |
| 87 | +## TODO (maybe) |
| 88 | +- ? How can we query the fatType of the SDFS (FAT16 or FAT32) to limit filenames to 8.3 on FAT16 ? |
| 89 | +- ? Add a visible root node "/" (with no delete option) + add the FS type next to it, like <i>LittleFS</i> |
| 90 | +- ? move "Mkdir" and "MkFile" to context menu, with prompt like for Rename/Move |
| 91 | +- ? implement drag/drop for move + make "rename" only a local rename operation (no move) |
| 92 | +- ? Optionally present SPIFFS as a hierarchical FS too |
| 93 | +- ? Optionally mount several filesystems at the same time (SPIFFS + SDFS or LittleFS + SDFS) |
| 94 | + |
| 95 | +## Test suite |
| 96 | +These tests are a checklist of operations to verify the FSBrowser behaviour. |
| 97 | +### On SPIFFS |
| 98 | +#### 8.3 filenames |
| 99 | +- At root : MkFile '/1.txt' / List / Edit / Download / Delete / Upload '/1.png' / View image / Delete image |
| 100 | +- In subdir : MkFile '/dir/2.txt' / List / Edit / Download / Delete / Upload '/dir/2.png' / View image |
| 101 | +- Create nested file '/a/b.txt' and delete it |
| 102 | +- Attempt creation of unsupported filenames |
| 103 | +#### Long filenames |
| 104 | +- At root : MkFile '/My text file 1.txt' / List / Edit / Download / Delete / Upload '/My image file 1.png' / View image / Delete image |
| 105 | +- In subdir : MkFile '/My Directory/My text 2.txt' / List / Edit / Download / Delete / Upload '/My Directory/My image 2.png' / View image |
| 106 | +- Create nested file '/My folder/My test file.txt' and delete it |
| 107 | + |
| 108 | +### On LittleFS |
| 109 | +#### 8.3 filenames |
| 110 | +- At root : MkFile '/1.txt' / List / Edit / Download / Delete / Upload '/1.png' / View image / Delete image / Mkdir '/dir' |
| 111 | +- In subdir : MkFile '/dir/2.txt' / List / Edit / Download / Delete / Upload '/dir/2.png' / View image / Mkdir '/dir/sub' |
| 112 | +- Delete root folder '/dir' |
| 113 | +- Create nested file '/a/b.txt' and delete file 'b.txt' |
| 114 | +#### Long filenames |
| 115 | +- At root : MkFile '/My text file 1.txt' / List / Edit / Download / Delete / Upload '/My image file 1.png' / View image / Delete image / Mkdir '/My Directory' |
| 116 | +- In subdir : MkFile '/My Directory/My text file 2.txt' / List / Edit / Download / Delete / Upload '/My Directory/My image file 2.png' / View image / Mkdir '/My Directory/My Subdirectory' |
| 117 | +- Delete root folder '/My Directory' |
| 118 | +- Create nested file '/My folder/My test file.txt' and delete file 'My test file.txt' |
| 119 | + |
| 120 | +### On SDFS |
| 121 | +#### 8.3 filenames |
| 122 | +- At root : MkFile '/1.txt' / List / Edit / Download / Delete / Upload '/1.png' / View image / Delete image / Mkdir '/dir' |
| 123 | +- In subdir : MkFile '/dir/2.txt' / List / Edit / Download / Delete / Upload '/dir/2.png' / View image / Mkdir '/dir/sub' |
| 124 | +- Delete root folder '/dir' |
| 125 | +- Create nested file '/a/b.txt' and delete file 'b.txt', then delete '/a' |
| 126 | +#### Long filenames |
| 127 | +- At root : MkFile '/My text file 1.txt' / List / Edit / Download / Delete / Upload '/My image file 1.png' / View image / Delete image / Mkdir '/My Directory' |
| 128 | +- In subdir : MkFile '/My Directory/My text file 2.txt' / List / Edit / Download / Delete / Upload '/My Directory/My image file 2.png' / View image / Mkdir '/My Directory/My Subdirectory' |
| 129 | +- Delete root folder '/My Directory' |
| 130 | +- Create nested file '/My folder/My test file.txt' and delete file 'My test file.txt' |
| 131 | + |
| 132 | +## Credits |
| 133 | +- Original version of FSBrowser written by me-no-dev, contributions over time by various contributors |
| 134 | +- Icons are from https://feathericons.com/ . The resulting PNG is passed first through https://compresspng.com/ before being converted to base64 using https://www.base64-image.de/ |
| 135 | +- The spinner is based on https://github.com/jlong/css-spinners |
| 136 | +- Minifiying of index.htm is done using the command line version of https://kangax.github.io/html-minifier/ |
| 137 | +- Idea of embedding webpage in code borrowed from https://github.com/me-no-dev/ESPAsyncWebServer |
| 138 | + |
0 commit comments