Update README.md

2024-02-29 08:54:28 +00:00 · 2024-02-29 08:54:28 +00:00 · 3c7a4ec8e1
parent eae6404f16
commit 3c7a4ec8e1
2 changed files with 96 additions and 0 deletions
--- a/README.MD
+++ b/README.MD
--- a/README.md
+++ b/README.md
@ -0,0 +1,96 @@
+# LwFTP Client
+
+A lightweight FTP client using FreeRTOS and the Netconn API from LwIP, designed for STM32 H7.
+
+## About The Project
+
+This project aims to provide a simple FTP client for embedded systems, enabling file operations over a network. It's built for systems running FreeRTOS and uses the Netconn API from LwIP for network communication.
+
+### Prerequisites:
+
+- STM32 H7 microcontroller
+- An FTP Server (tested with Windows IIS Server Manager)
+- FreeRTOS
+- LwIP with Netconn API (requires RTOS mode)
+- This repository
+
+## Initialization
+
+To initialize the LwFTP client, follow these steps:
+
+1. **Add the following declarations in the `/* USER CODE BEGIN PV */` sections**
+    ```C
+    /* USER CODE BEGIN PV */
+    static lwftp_session_t s;
+    uint8_t CLI_IP[4] = { 192, 168, 0, 120 };    // Client IP address
+    uint8_t SVR_IP[4] = { 192, 168, 0, 100 };    // Server IP address
+    u16_t SVR_PORT = 21;                         // FTP server port, typically 21
+    char *USER = "anonymous";                    // FTP login username
+    char *PASS = "email@example.com";            // FTP login password
+    /* USER CODE END PV */
+    ```
+
+2. **Declare `lwftp_init()` in the main file**
+
+    example:
+
+    ```c
+    void lwftp_init(void) {
+        IP4_ADDR(&s.cli_ip, CLI_IP[0], CLI_IP[1], CLI_IP[2], CLI_IP[3]);
+        IP4_ADDR(&s.svr_ip, SVR_IP[0], SVR_IP[1], SVR_IP[2], SVR_IP[3]);
+        s.svr_port = SVR_PORT;
+        s.user = USER;
+        s.pass = PASS;
+
+        debugPrint("\n>> lwftp: cli ip: %d.%d.%d.%d\r\n", CLI_IP[0], CLI_IP[1], CLI_IP[2], CLI_IP[3]);
+        debugPrint(">> lwftp: svr ip: %d.%d.%d.%d\r\n", SVR_IP[0], SVR_IP[1], SVR_IP[2], SVR_IP[3]);
+        debugPrint(">> lwftp: svr port: %d\r\n", s.svr_port);
+        debugPrint(">> lwftp: username: %s\r\n", s.user);
+        debugPrint(">> lwftp: password: %s\r\n\n", s.pass);
+
+        // Initialize threads for FTP connections
+        sys_thread_new("lwftp_ctrl_thread", lwftp_ctrl_thread, (void*) &s, DEFAULT_THREAD_STACKSIZE, osPriorityNormal);
+        sys_thread_new("lwftp_data_thread", lwftp_data_thread, (void*) &s, DEFAULT_THREAD_STACKSIZE, osPriorityNormal);
+    }
+    ```
+
+3. **Call `lwftp_init()` from the user code area** of `StartDefaultTask()` in `main.c`, right after `MX_LWIP_Init()`
+
+    example:
+
+    ```c
+    void StartDefaultTask(void const * argument)
+    {
+        /* init code for LWIP */
+        MX_LWIP_Init();
+        /* USER CODE BEGIN 5 */
+        lwftp_init();
+        /* Infinite loop */
+        for (;;) {
+            osDelay(1);
+        }
+        /* USER CODE END 5 */
+    }
+    ```
+## Main Features & Limitations
+
+- **Storing Files:** `err = lwftp_store(&s, <filename.extension>, <data>);`
+    - *Under development:* A feature to prevent overwriting duplicate files.
+
+- **Retrieving Files:** `err = lwftp_retrieve(&s, <filename.extension>);`
+    - *Limitation:* May omit excessively long content. This issue is pending resolution.
+
+- **Listing Files:** `err = lwftp_list(&s, fileList);`
+    - To retrieve a list of files from the server's root directory, declare a character array (e.g., `char *fileList[500];`) and pass it as an argument.
+    - *Note:* Path specification is not implemented. 
+    - *Note:* The output format of the file list may vary between servers, requiring careful parsing.
+
+- **Closing Connection:** `err = lwftp_close(&s);`
+    - closes the FTP connection.
+
+## Features for debugging
+
+- **Enabling LwFTP Debugging Output**
+
+  To enable verbose debugging output for LwFTP, modify the `LWFTP_DEBUG` comment value in `lwftp.h`.
+