https://github.com/nopnop2002/esp-idf-ftpserver
ftp server for esp-idf using FAT file system
https://github.com/nopnop2002/esp-idf-ftpserver
esp-idf esp32 fat32 ftp ftp-server
Last synced: about 1 month ago
JSON representation
ftp server for esp-idf using FAT file system
- Host: GitHub
- URL: https://github.com/nopnop2002/esp-idf-ftpserver
- Owner: nopnop2002
- License: mit
- Created: 2021-02-13T08:55:43.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-06-27T03:38:02.000Z (3 months ago)
- Last Synced: 2025-06-27T04:53:48.124Z (3 months ago)
- Topics: esp-idf, esp32, fat32, ftp, ftp-server
- Language: C
- Homepage:
- Size: 220 KB
- Stars: 46
- Watchers: 1
- Forks: 15
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# esp-idf-ftpServer
FTP Server for esp-idf using FATFS/LittleFS.
I found [this](https://www.esp32.com/viewtopic.php?f=13&t=5013#p21738) information.
So, I ported from [here](https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo/blob/master/MicroPython_BUILD/components/micropython/esp32/libs/ftp.c).
Directory operations are possible because FATFS/LittlsFS is used.
# Difference between FATFS and LittleFS
- FATFS
Case insensitive.
```
ftp> dir
227 (192,168,10,130,7,232)
150
-rw-rw-rw- 1 root root 41 May 08 00:47 long_file_name_support.txt
drw-rw-rw- 1 root root 0 May 08 00:48 sub_directory1
drw-rw-rw- 1 root root 0 May 08 00:48 sub_directory2
```
- LittleFS
Case sensitive.
```
ftp> dir
227 (192,168,10,130,7,232)
150
-rw-rw-rw- 1 root root 41 May 08 00:51 LONG_FILE_NAME_SUPPORT.txt
drw-rw-rw- 1 root root 0 Dec 31 1969 SUB_DIRECTORY1
drw-rw-rw- 1 root root 0 Dec 31 1969 SUB_DIRECTORY2
-rw-rw-rw- 1 root root 41 May 08 00:51 long_file_name_support.txt
drw-rw-rw- 1 root root 0 Dec 31 1969 sub_directory1
drw-rw-rw- 1 root root 0 Dec 31 1969 sub_directory2
```
# Software requirements
ESP-IDF V5.0 or later.
ESP-IDF V4.4 release branch reached EOL in July 2024.
ESP-IDF V5.1 is required when using ESP32-C6.
# Installation
```
git clone https://github.com/nopnop2002/esp-idf-ftpServer
cd esp-idf-ftpServer/
idf.py set-target {esp32/esp32s2/esp32s3/esp32c2/esp32c3/esp32c6}
idf.py menuconfig
idf.py flash monitor
```
# Partition table for Builtin SPI Flash Memory
If you select FATFS on the built-in SPI flash memory, this project will use partitions_example_fatfs.csv.
If you select LittleFS on the built-in SPI flash memory, this project will use partitions_example_littlefs.csv.
If your board has 4M SPI Flash Memory, you can get more space by changing this.
The maximum partition size that can be specified for the 4M flash model is 0x2F0000(=2,960K).
If you use 4M SPI Flash Memory, you need to change this.
# Configuration
## File System Selection
This project supports the following file systems.
You can select any one using menuconfig.
- LittleFS on Builtin SPI Flash Memory
- FATFS on Builtin SPI Flash Memory
- FATFS on SD card with SDSPI Interface
- FATFS on SD card with SDMMC Interface (Valid only for ESP32/ESP32S3)
Besides this, ESP32 supports SPIFFS, but this project will not use SPIFFS because it cannot handle directories.
When using SD card with SDMMC, you can select 1 Line mode or 4 Line mode.
Note:
The connection when using SDSPI, SDMMC will be described later.
Note:
LittleFS requires ESP-IDF V5.2 or later.
## WiFi Setting for Station-MODE
You can connect using the mDNS hostname instead of the IP address.
You can use static IP.
## WiFi Setting for AccessPoint-MODE
## FTP Server Setting
# Using FATFS on SD card with SDSPI Interface
|ESP32|ESP32S2/S3|ESP32C2/C3/C6|SPI card pin|Notes|
|:-:|:-:|:-:|:-:|:--|
|GPIO23|GPIO35|GPIO01|MOSI|10k pullup if can't mount|
|GPIO19|GPIO37|GPIO03|MISO||
|GPIO18|GPIO36|GPIO02|SCK||
|GPIO14|GPIO34|GPIO04|CS|||
|3.3V|3.3V|3.3V|VCC|Don't use 5V supply|
|GND|GND|GND|GND||
__You can change it to any pin using menuconfig.__
Note:
This project doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.
Click [here](https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card/sdspi) for details.
# Using FATFS on SD card with SDMMC Interface
On ESP32, SDMMC peripheral is connected to specific GPIO pins using the IO MUX.
__GPIO pins cannot be customized.__
GPIO2 and GPIO12 cannot be changed.
Since these GPIOs are BootStrap, it is very tricky to use 4-line SD mode with ESP32.
Click [here](https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card/sdmmc) for details.
|ESP32 pin|SD card pin|Notes|
|:-:|:-:|:--|
|GPIO14|CLK|10k pullup|
|GPIO15|CMD|10k pullup|
|GPIO2|D0|10k pullup or connect to GPIO0|
|GPIO4|D1|not used in 1-line SD mode; 10k pullup in 4-line SD mode|
|GPIO12|D2|not used in 1-line SD mode; 10k pullup in 4-line SD mode|
|GPIO13|D3|not used in 1-line SD mode, but card's D3 pin must have a 10k pullup
|N/C|CD|not used in this project|
|N/C|WP|not used in this project|
|3.3V|VCC|Don't use 5V supply|
|GND|GND||
On ESP32-S3, SDMMC peripheral is connected to GPIO pins using GPIO matrix.
__This allows arbitrary GPIOs to be used to connect an SD card.__
Click [here](https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card/sdmmc) for details.
The default settings are as follows. But you can change it.
|ESP32-S3 pin|SD card pin|Notes|
|:-:|:-:|:--|
|GPIO36|CLK|10k pullup|
|GPIO35|CMD|10k pullup|
|GPIO37|D0|10k pullup|
|GPIO38|D1|not used in 1-line SD mode; 10k pullup in 4-line SD mode|
|GPIO33|D2|not used in 1-line SD mode; 10k pullup in 4-line SD mode|
|GPIO34|D3|not used in 1-line SD mode, but card's D3 pin must have a 10k pullup
|N/C|CD|not used in this project|
|N/C|WP|not used in this project|
|3.3V|VCC|Don't use 5V supply|
|GND|GND||
# Using long file name support
By default, FATFS file names can be up to 8 characters long.
If you use filenames longer than 8 characters, you need to change the values below.
Long File Name on FLASH.
Long File Name on SDCARD.
Short File Name on SDCARD
# Changing sector size when using wear levelling library
By default, 4096-byte sectors are used.
You can change it to 512-byte sectors using menuconfig.
The 512-byte sector has Performance mode and Safety mode.
# Performance of each mode
Using ESP32-CAM board and SanDisk Ultra 16GB Micro SD CARD.
Enable Long filename support (Long filename buffer in heap).
|File Syetem|Sector Size|Mode|Write Speed|Read Speed|
|:-:|:-:|:-:|:-:|:-:|
|LittlsFS on Builtin SPI Flash Memory|||51 kB/s|1678 kB/s|
|FATFS on Builtin SPI Flash Memory|512|Safety|2 kB/s|1735 kB/s|
|FATFS on Builtin SPI Flash Memory|512|Performance|5 kB/s|1735 kB/s|
|FATFS on Builtin SPI Flash Memory|4096||46 kB/s|2625 kB/s|
|FATFS on SD card with SDSPI Interface|4096||398 kB/s|610 kB/s|
|FATFS on SD card with SDMMC Interface|4096|1Line|499 kB/s|875kB/s|
|FATFS on SD card with SDMMC Interface|4096|4Line|572 kB/s|1190 kB/s|
# Limitations
- The server does not support multiple connections.
- The server does not support active connection.
__Only passive connections are supported.__
Unfortunately, Windows standard ftp.exe does not allow passive mode (PASV) connections.
If you have to make a passive mode connection On Windows, you need to use another software such as FFFTP / WinSCP / FileZilla to connect in passive mode.
- The server can only process these commands.
* SYST
* CDUP
* CWD
* PWD
* XPWD(Same as PWD)
* SIZE
* MDTM(Always GMT)
* TYPE
* USER
* PASS
* PASV
* LIST
* RETR
* STOR
* DELE
* RMD
* MKD
* RNFR(Rename From)
* RNTO(Rename To)
* NOOP
* QUIT
* APPE
* NLST
# Using LilyGo ESP32-S2
The LilyGo ESP32-S2 development board has a micro SD card slot on the board.
It is connected to the ESP32 by SPI, and the peripheral power is supplied from GPIO14.
With this, you can easily build an FTP server.
__No equipment other than the development board is required.__
It works very stably.
# Windows ftp client
I tested these client.
__You need to set the connection type to Passive Mode.__
- WinSCP
- FileZilla
You need to make this setting when using FileZilla.
- FFFTP
- Windows standard ftp.exe
Unfortunately, Windows standard ftp.exe does not allow passive mode (PASV) connections.
# Troubleshooting
I sometimes get this error when using external SPI SD card readers.
Requires a PullUp resistor.
You can see all the logging on the server side by commenting it out here.
```
void ftp_task (void *pvParameters)
{
ESP_LOGI(FTP_TAG, "ftp_task start");
//esp_log_level_set(FTP_TAG, ESP_LOG_WARN); ------------> Comment out
strcpy(ftp_user, CONFIG_FTP_USER);
strcpy(ftp_pass, CONFIG_FTP_PASSWORD);
ESP_LOGI(FTP_TAG, "ftp_user:[%s] ftp_pass:[%s]", ftp_user, ftp_pass);
```
# Reference
https://github.com/nopnop2002/esp-idf-ftpClient