README.md
1| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 |
2| ----------------- | ----- | -------- | -------- |
3
4# Simple HTTP File Server Example
5
6(See the README.md file in the upper level 'examples' directory for more information about examples.)
7
8If the SD card option is enabled, you can access files in the SD card by the path `/sdcard`
9
10HTTP file server example demonstrates file serving with both upload and download capability, using the `esp_http_server` component of ESP-IDF. The following URIs are provided by the server:
11
12| URI | Method | Description |
13|----------------------|---------|-------------------------------------------------------------------------------------------|
14|`index.html` | GET | Redirects to `/` |
15|`favicon.ico` | GET | Browsers use this path to retrieve page icon which is embedded in flash |
16|`/` | GET | Responds with webpage displaying list of files on SPIFFS and form for uploading new files |
17|`/<file path>` | GET | For downloading files stored on SPIFFS |
18|`/upload/<file path>` | POST | For uploading files on to SPIFFS. Files are sent as body of HTTP post requests |
19|`/delete/<file path>` | POST | Command for deleting a file from SPIFFS |
20
21File server implementation can be found under `main/file_server.c` which uses SPIFFS for file storage. `main/upload_script.html` has some HTML, JavaScript and Ajax content used for file uploading, which is embedded in the flash image and used as it is when generating the home page of the file server.
22
23## Note
24
25`/index.html` and `/favicon.ico` can be overridden by uploading files with same pathname to SPIFFS.
26
27## Usage
28
29* Open the project configuration menu (`idf.py menuconfig`) go to `Example Configuration` ->
30 1. WIFI SSID: WIFI network to which your PC is also connected to.
31 2. WIFI Password: WIFI password
32
33* In order to test the file server demo :
34 1. compile and burn the firmware `idf.py -p PORT flash`
35 2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80
36 3. test the example interactively on a web browser (assuming IP is 192.168.43.130):
37 1. open path `http://192.168.43.130/` or `http://192.168.43.130/index.html` to see an HTML web page with list of files on the server (initially empty)
38 2. use the file upload form on the webpage to select and upload a file to the server
39 3. click a file link to download / open the file on browser (if supported)
40 4. click the delete link visible next to each file entry to delete them
41 4. test the example using curl (assuming IP is 192.168.43.130):
42 1. `myfile.html` is uploaded to `/path/on/device/myfile_copy.html` using `curl -X POST --data-binary @myfile.html 192.168.43.130:80/upload/path/on/device/myfile_copy.html`
43 2. download the uploaded copy back : `curl 192.168.43.130:80/path/on/device/myfile_copy.html > myfile_copy.html`
44 3. compare the copy with the original using `cmp myfile.html myfile_copy.html`
45
46* To write to SD card, you need to:
47 1. Select the `Mount the SD card to the filesystem` in the configuration menu (by calling `idf.py menuconfig` and select the `EXAMPLE_MOUNT_SD_CARD` option.
48 2. If you need to format the card while the card fails to be mounted, enable the config option `The card will be formatted if mount has failed` (`EXAMPLE_FORMAT_SDCARD_IF_MOUNT_FAILED`). Be careful, all the data in the card will disappear.
49
50 Note: You will have to access the SD card by SPI bus with sdspi driver, if you are using ESP32S2.
51
52## Note
53
54Browsers often send large header fields when an HTML form is submit. Therefore, for the purpose of this example, `HTTPD_MAX_REQ_HDR_LEN` has been increased to 1024 in `sdkconfig.defaults`. User can adjust this value as per their requirement, keeping in mind the memory constraint of the hardware in use.
55
56## Example Output
57
58```
59I (5583) example_connect: Got IPv6 event: Interface "example_connect: sta" address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
60I (5583) example_connect: Connected to example_connect: sta
61I (5593) example_connect: - IPv4 address: 192.168.194.219
62I (5593) example_connect: - IPv6 address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
63I (5603) example: Initializing SPIFFS
64I (5723) example: Partition size: total: 896321, used: 0
65I (5723) file_server: Starting HTTP Server on port: '80'
66I (28933) file_server: Receiving file : /test.html...
67I (28933) file_server: Remaining size : 574
68I (28943) file_server: File reception complete
69I (28993) file_server: Found file : test.html (574 bytes)
70I (35943) file_server: Sending file : /test.html (574 bytes)...
71I (35953) file_server: File sending complete
72I (45363) file_server: Deleting file : /test.html
73```
74
