{"id":16239508,"url":"https://github.com/nopnop2002/esp-idf-ftpclient","last_synced_at":"2025-04-08T03:09:19.896Z","repository":{"id":49784427,"uuid":"213092593","full_name":"nopnop2002/esp-idf-ftpClient","owner":"nopnop2002","description":"ftp client for esp-idf","archived":false,"fork":false,"pushed_at":"2025-03-30T00:50:47.000Z","size":149,"stargazers_count":78,"open_issues_count":0,"forks_count":12,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-31T17:19:22.855Z","etag":null,"topics":["esp-idf","esp32","ftp","ftp-client"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nopnop2002.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-06T01:15:23.000Z","updated_at":"2025-03-31T00:35:34.000Z","dependencies_parsed_at":"2024-02-27T04:23:48.107Z","dependency_job_id":"34eddf06-84f7-46c3-8a65-4b6e4d704d5d","html_url":"https://github.com/nopnop2002/esp-idf-ftpClient","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nopnop2002%2Fesp-idf-ftpClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nopnop2002%2Fesp-idf-ftpClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nopnop2002%2Fesp-idf-ftpClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nopnop2002%2Fesp-idf-ftpClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nopnop2002","download_url":"https://codeload.github.com/nopnop2002/esp-idf-ftpClient/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247767234,"owners_count":20992547,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp-idf","esp32","ftp","ftp-client"],"created_at":"2024-10-10T13:43:56.131Z","updated_at":"2025-04-08T03:09:19.888Z","avatar_url":"https://github.com/nopnop2002.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# esp-idf-ftpClient\nFTP Client for esp-idf.   \n\n# Software requirements   \nESP-IDF V5.0 or later.   \nESP-IDF V4.4 release branch reached EOL in July 2024.   \n\n# Installation\n```\ngit clone https://github.com/nopnop2002/esp-idf-ftpClient\ncd esp-idf-ftpClient/\nidf.py menuconfig\nidf.py flash\n```\n\n# Configuration\n\n![config-top](https://user-images.githubusercontent.com/6020549/165466546-f6609f93-679d-4de9-9b45-db11b723d815.jpg)\n![config-app](https://user-images.githubusercontent.com/6020549/165466556-7c5770da-e75b-4aa8-a49f-43c975233809.jpg)\n\n## File System Selection   \nThis project supports the following file systems.   \nYou can select any one using menuconfig.   \n- SPIFFS file system on Builtin SPI Flash Memory   \n- FAT file system on Builtin SPI Flash Memory   \n- LITTLEFS file system on Builtin SPI Flash Memory   \n- FAT file system on SPI peripheral SDCARD   \n- FAT file system on SDMMC peripheral SDCARD(Valid only for ESP32/ESP32S3)   \n- FAT file system on External SPI Flash Memory like Winbond W25Q64    \n\n![config-file-system-builtin-spiffs](https://github.com/user-attachments/assets/b4b2ad4c-f5f0-4994-98c7-8af8ff7b09a5)\n![config-file-system-builtin-fatfs](https://github.com/user-attachments/assets/39b74b16-4df5-427e-8285-93e48e41992e)\n![config-file-system-builtin-littlefs](https://github.com/user-attachments/assets/72eb1497-680d-475e-ba52-d4ec0852c441)\n\nNote:   \nThe connection when using SDSPI, SDMMC, and External SPI flash Memory will be described later.   \n\nNote:   \nLITTLEFS requires ESP-IDF V5.2 or later.\n\n## Partition table   \nUse ```partitions_example_spiffs.csv``` when you select SPIFFS file system on Builtin SPI Flash Memory.   \nUse ```partitions_example_fatfs.csv``` when you select FAT file system on Builtin SPI Flash Memory.   \nUse ```partitions_example_littlefs.csv``` when you select LITTLEFS file system on Builtin SPI Flash Memory.   \n\n__If you need more storage space in the Builtin SPI Flash Memory, you will need to modify these files.__   \n\n## Wifi Setting   \n\n![config-wifi](https://user-images.githubusercontent.com/6020549/165469815-dfe6407b-4598-4cc7-8f60-4ceef4618529.jpg)\n\n\n## FTP Server Setting   \n\n![config-ftp-server](https://user-images.githubusercontent.com/6020549/187052709-7873970e-c72e-4ea0-b904-85e1b0afc799.jpg)\n\n- Public FTP Server   \n\tYou can use [this](https://dlptest.com/ftp-test/) public FTP server for testing.   \n\tThe files will be stored for 10 minutes before being deleted.   \n\t```\n\tcd esp-idf-ftpClient\n\trm sdkconfig\n\tcd main\n\tcp Kconfig.projbuild Kconfig.projbuild.old\n\tcp Kconfig.projbuild.dlptest Kconfig.projbuild\n\tcd ..\n\tidf.py menuconfig\n\tidf.py build\n\t```\n\t![Image](https://github.com/user-attachments/assets/3fc731ff-b081-4807-9b34-c8aa8513a6e2)\n\n- FTP Server using python   \n\tYou can set up an FTP server with [this](https://github.com/nopnop2002/esp-idf-ftpClient/tree/master/python-ftp-server) script.\n\n\n# Using FAT file system on SPI peripheral SDCARD\n\n|ESP32|ESP32S2/S3|ESP32C2/C3/C6|SD card pin|Notes|\n|:-:|:-:|:-:|:-:|:--|\n|GPIO23|GPIO35|GPIO01|MOSI|10k pull up if can't mount|\n|GPIO19|GPIO37|GPIO03|MISO||\n|GPIO18|GPIO36|GPIO02|SCK||\n|GPIO5|GPIO34|GPIO04|CS||\n|3.3V|3.3V|3.3V|VCC|Don't use 5V supply|\n|GND|GND|GND|GND||\n\n![config-file-system-sdspi](https://user-images.githubusercontent.com/6020549/194224614-703f6ee3-303f-4f81-a25a-4e26b3297f2b.jpg)\n\n__You can change it to any pin using menuconfig.__   \n\nNote:   \nThis project doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.   \n\n\n# Using FAT file system on SDMMC peripheral SDCARD\n\nOn ESP32, SDMMC peripheral is connected to specific GPIO pins using the IO MUX.   \n__GPIO pins cannot be customized.__   \nGPIO2 and GPIO12 cannot be changed.   \nSo using 4-line SD mode with ESP32 is very tricky.   \nPlease see the table below for the pin connections.\n\n|ESP32 pin|SD card pin|Notes|\n|:-:|:-:|:--|\n|GPIO14|CLK|10k pullup|\n|GPIO15|CMD|10k pullup|\n|GPIO2|D0|10k pullup or connect to GPIO00|\n|GPIO4|D1|not used in 1-line SD mode; 10k pullup in 4-line SD mode|\n|GPIO12|D2|not used in 1-line SD mode; 10k pullup in 4-line SD mode|\n|GPIO13|D3|not used in 1-line SD mode, but card's D3 pin must have a 10k pullup\n|N/C|CD|not used in this project|\n|N/C|WP|not used in this project|\n|3.3V|VCC|Don't use 5V supply|\n|GND|GND||\n\n- 1line mode   \n![config-file-system-sdmmc-esp32](https://user-images.githubusercontent.com/6020549/165658970-6956c9c4-eb24-44fe-99c2-758045300adc.jpg)\n\n- 4line mode   \n![config-file-system-sdmmc-esp32-4line](https://github.com/user-attachments/assets/5821a686-8ca0-40cc-b0c6-ad247ee29c4b)\n\nOn ESP32-S3, SDMMC peripheral is connected to GPIO pins using GPIO matrix.   \n__This allows arbitrary GPIOs to be used to connect an SD card.__   \n\n|ESP32-S3 pin|SD card pin|Notes|\n|:-:|:-:|:--|\n|GPIO36|CLK|10k pullup|\n|GPIO35|CMD|10k pullup|\n|GPIO37|D0|10k pullup|\n|GPIO38|D1|not used in 1-line SD mode; 10k pullup in 4-line SD mode|\n|GPIO33|D2|not used in 1-line SD mode; 10k pullup in 4-line SD mode|\n|GPIO34|D3|not used in 1-line SD mode, but card's D3 pin must have a 10k pullup\n|N/C|CD|not used in this project|\n|N/C|WP|not used in this project|\n|3.3V|VCC|Don't use 5V supply|\n|GND|GND||\n\n- 1line mode   \n![config-file-system-sdmmc-esp32s3](https://user-images.githubusercontent.com/6020549/165659001-8e767614-39e5-4e19-9e90-8ce0c8e79f57.jpg)\n\n- 4line mode   \n![config-file-system-sdmmc-esp32s3-4line](https://github.com/user-attachments/assets/ddb93c01-07a3-41f7-8cf7-07bea2a8014d)\n\n## Note about GPIO2 (ESP32 only)   \nGPIO2 pin is used as a bootstrapping pin, and should be low to enter UART download mode. One way to do this is to connect GPIO0 and GPIO2 using a jumper, and then the auto-reset circuit on most development boards will pull GPIO2 low along with GPIO0, when entering download mode.\n\n- Some boards have pulldown and/or LED on GPIO2. LED is usually ok, but pulldown will interfere with D0 signals and must be removed. Check the schematic of your development board for anything connected to GPIO2.\n\n## Note about GPIO12 (ESP32 only)   \nGPIO12 is used as a bootstrapping pin to select output voltage of an internal regulator which powers the flash chip (VDD_SDIO).   \nThis pin has an internal pulldown so if left unconnected it will read low at reset (selecting default 3.3V operation).   \nWhen adding a pullup to this pin for SD card operation, consider the following:\n- For boards which don't use the internal regulator (VDD_SDIO) to power the flash, GPIO12 can be pulled high.\n- For boards which use 1.8V flash chip, GPIO12 needs to be pulled high at reset. This is fully compatible with SD card operation.\n- On boards which use the internal regulator and a 3.3V flash chip, GPIO12 must be low at reset. This is incompatible with SD card operation.\n    * In most cases, external pullup can be omitted and an internal pullup can be enabled using a `gpio_pullup_en(GPIO_NUM_12);` call. Most SD cards work fine when an internal pullup on GPIO12 line is enabled. Note that if ESP32 experiences a power-on reset while the SD card is sending data, high level on GPIO12 can be latched into the bootstrapping register, and ESP32 will enter a boot loop until external reset with correct GPIO12 level is applied.\n    * Another option is to burn the flash voltage selection efuses. This will permanently select 3.3V output voltage for the internal regulator, and GPIO12 will not be used as a bootstrapping pin. Then it is safe to connect a pullup resistor to GPIO12. This option is suggested for production use.\n\n# Using FAT file system on External SPI Flash Memory\nI tested these SPI Flash Memory.   \nhttps://github.com/nopnop2002/esp-idf-w25q64\n\n|#|W25Q64||ESP32|ESP32-S2/S3|ESP32-C2/C3/C6|\n|:-:|:-:|:-:|:-:|:-:|:-:|\n|1|/CS|--|GPIO5|GPIO10|GPIO4|\n|2|MISO|--|GPIO19|GPIO13|GPIO3|\n|3|/WP|--|3.3V|3.3V|3.3V|\n|4|GND|--|GND|GND|GND|\n|5|MOSI|--|GPIO23|GPIO11|GPIO1|\n|6|SCK|--|GPIO18|GPIO12|GPIO2|\n|7|/HOLD|--|3.3V|3.3V|3.3V|\n|8|VCC|--|3.3V|3.3V|3.3V|\n\n![config-file-system-external-fatfs](https://github.com/user-attachments/assets/4f98df6c-1c4a-40a7-84e0-d6e7198f30e0)\n\nNote: You will get an error. It works fine after a few resets. At the moment, it is not stable.   \n```\nI (2121) FTP: Initializing external SPI Flash\nI (2121) FTP: Pin assignments:\nI (2121) FTP: MOSI: 23   MISO: 19   SCLK: 18   CS:  5\nE (2131) memspi: no response\nE (2131) FTP: Failed to initialize external Flash: ESP_ERR_INVALID_RESPONSE (0x108)\n```\n\nAfter reset   \n```\nI (1621) FTP: Initializing external SPI Flash\nI (1621) FTP: Pin assignments:\nI (1631) FTP: MOSI: 23   MISO: 19   SCLK: 18   CS:  5\nI (1631) spi_flash: detected chip: winbond\nI (1641) spi_flash: flash io: dio\nI (1641) FTP: Initialized external Flash, size=8192 KB, ID=0xef4017\nI (1651) FTP: Adding external Flash as a partition, label=\"storage\", size=8192 KB\nI (1661) FTP: Initializing FAT file system\nI (1661) FTP: Mount FAT filesystem on /root\n```\n\n\n# Using ESP32-CAM\nThe ESP32-CAM development board has a micro SD card slot on the board.   \nIt is connected to the ESP32 by SDMMC with 4-line Mode.   \n__No equipment other than the development board is required.__   \nIt works very stably.   \n\n![ESP32-CAM-1](https://github.com/user-attachments/assets/89317896-e88e-460a-b658-e224ae5b9d83)\n![ESP32-CAM-2](https://github.com/user-attachments/assets/911b6683-d93a-4a9b-8f18-3c46515d698b)\n![ESP32-CAM-3](https://github.com/user-attachments/assets/287c2e53-f80a-457e-aba3-bfe745c3e2b8)\n\n\n# Using LilyGo ESP32-S2\nThe LilyGo ESP32-S2 development board has a micro SD card slot on the board.   \nIt is connected to the ESP32 by SPI, and the peripheral power is supplied from GPIO14.   \n__No equipment other than the development board is required.__   \nIt works very stably.   \n\n|ESP32 pin|SPI bus signal|\n|:-:|:-:|\n|GPIO11|MOSI|\n|GPIO13|MISO|\n|GPIO12|SCK|\n|GPIO10|CS|\n|GPIO14|POWER|\n\n![LilyGo-esp32-s2-1](https://user-images.githubusercontent.com/6020549/107864770-00f96100-6ea3-11eb-8549-6885ae398111.JPG)\n![LilyGo_ESP32-S2-2](https://github.com/user-attachments/assets/69513704-cdd7-47f3-a48a-756524c4b5fb)\n![LilyGo_ESP32-S2-3](https://github.com/user-attachments/assets/6d62b8ba-696c-4907-99a2-1fb6cc862efe)\n\n\n\n\n# API\nBased on [ftplib](https://nbpfaus.net/~pfau/ftplib/ftplib.html) V4.0-1.   \n\n## Server Connection\n- ftpClientConnect() - Connect to a remote server\n- ftpClientLogin() - Login to remote machine\n- ftpClientQuit() - Disconnect from remote server\n- ftpClientSetOptions() - Set Connection Options\n\n## Directory Functions\n- ftpClientChangeDir() - Change working directory\n- ftpClientMakeDir() - Create a directory\n- ftpClientRemoveDir() - Remove a directory\n- ftpClientDir() - List a remote directory\n- ftpClientNlst() - List a remote directory\n- ftpClientChangeDirUp() - Change to parent directory\n- ftpClientPwd() - Determine current working directory\n\n## File to File Transfer\n- ftpClientGet() - Retreive a remote file\n- ftpClientPut() - Send a local file to remote\n- ftpClientDelete() - Delete a remote file\n- ftpClientRename() - Rename a remote file\n\n## File to Program Transfer\nThese routines allow programs access to the data streams connected to remote files and directories.   \n- ftpClientAccess() - Open a remote file or directory\n- ftpClientRead() - Read from remote file or directory\n- ftpClientWrite() - Write to remote file\n- ftpClientClose() - Close data connection\n\n# Using long file name support   \nBy default, FATFS file names can be up to 8 characters long.   \nIf you use filenames longer than 8 characters, you need to change the values below.   \n![config_long_file_name_support-1](https://github.com/nopnop2002/esp-idf-ftpServer/assets/6020549/dbae8910-74c9-4702-bdd4-881246e3fb95)\n![config_long_file_name_support-2](https://github.com/nopnop2002/esp-idf-ftpServer/assets/6020549/75d1ea99-86ff-40c0-8ffc-8bd30b9fc32e)\n![config_long_file_name_support-3](https://github.com/nopnop2002/esp-idf-ftpServer/assets/6020549/6e381627-e6f4-494d-ad40-04a73b49727b)\n\n\n# Screen Shot   \n![ScrrenShot](https://user-images.githubusercontent.com/6020549/107837485-5f133f00-6de4-11eb-9fe8-775443c6836d.jpg)\n- Get remote file list   \n- Write local file   \n- Put file to server   \n- Remove local file   \n- Get file from sever   \n- Read local file   \n\n\n# Truble shooting   \nBy changing this, you can see the response from the server:\n```\n#define FTP_CLIENT_DEBUG                    2\n```\n\n\n\n# How to use this component in your project   \nCreate idf_component.yml in the same directory as main.c.   \n```\nYourProject --+-- CMakeLists.txt\n              +-- main --+-- main.c\n                         +-- CMakeLists.txt\n                         +-- idf_component.yml\n```\n\nContents of idf_component.yml.\n```\ndependencies:\n  nopnop2002/ftpClient:\n    path: components/ftpClient/\n    git: https://github.com/nopnop2002/esp-idf-ftpClient.git\n```\n\nWhen you build a projects esp-idf will automaticly fetch repository to managed_components dir and link with your code.   \n```\nYourProject --+-- CMakeLists.txt\n              +-- main --+-- main.c\n              |          +-- CMakeLists.txt\n              |          +-- idf_component.yml\n              +-- managed_components ----- nopnop2002__ftpClient\n```\n\n\n# Reference   \n- FTP Server using FAT File system.   \nSince it uses the FAT file system instead of SPIFFS, directory operations are possible.   \nhttps://github.com/nopnop2002/esp-idf-ftpServer   \n\n- File copy using scp.   \nhttps://github.com/nopnop2002/esp-idf-scp-client\n\n- File copy using smb.   \nhttps://github.com/nopnop2002/esp-idf-smb-client\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnopnop2002%2Fesp-idf-ftpclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnopnop2002%2Fesp-idf-ftpclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnopnop2002%2Fesp-idf-ftpclient/lists"}