feat(usb_host_msc): support multple character encodings

Author: laride

examples/usb/device/usb_msc_wireless_disk/README.md

@@ -42,9 +42,10 @@ This demo has enabled FATFS OEM multi-code page support. To manually adjust mult
 
 - (Top) → <kbd>Component config</kbd> → <kbd>FAT Filesystem support</kbd> → <kbd>OEM Code Page</kbd>
   - This example defaults to <kbd>Dynamic (all code pages supported)</kbd>.
-  - When set to <kbd>Dynamic (all code pages supported)</kbd> (`FATFS_CODEPAGE_DYNAMIC`), FATFS will support all code pages, but will increase the compiled binary size by ~500kB.
-  - When set to other code pages, you need to select a code page that matches the character set of the filenames, otherwise it may cause garbled characters, inability to find files, or other hidden issues.
+  - When set to <kbd>Dynamic (all code pages supported)</kbd> (`FATFS_CODEPAGE_DYNAMIC`), FATFS will support all code pages, but it will increase the size of the compiled output by about 500 kB.
+  - If you choose another code page, make sure that the selected code page matches the character set used in the filenames; otherwise it may cause garbled text, file not found errors, or other latent issues.
 - (Top) → <kbd>Component config</kbd> → <kbd>FAT Filesystem support</kbd> → <kbd>API character encoding</kbd>
   - This example defaults to <kbd>API uses UTF-8 encoding</kbd> (`FATFS_API_ENCODING_UTF_8`).
-  - This option controls the encoding used by FATFS API for reading filenames. Please refer to the description of this configuration item for details.
+  - This option controls the encoding method used by the filenames read by the FATFS API. For more details, please refer to the configuration help.
   - For web development, it is recommended to use UTF-8 encoding.
+

examples/usb/device/usb_msc_wireless_disk/README_cn.md

@@ -42,9 +42,9 @@
 
 - (Top) → <kbd>Component config</kbd> → <kbd>FAT Filesystem support</kbd> → <kbd>OEM Code Page</kbd>
   - 本例程默认为 <kbd>Dynamic (all code pages supported)</kbd>。
-  - 设置为 <kbd>Dynamic (all code pages supported)</kbd> （`FATFS_CODEPAGE_DYNAMIC`）时，FATFS 将支持所有代码页，但会使编译产物增大 ~500kB。
-  - 设置为其他代码页时，需要选择与文件名字符集相匹配的代码页，否则会导致乱码、无法找到文件或其他隐性问题。
+  - 将其设置为 <kbd>Dynamic (all code pages supported)</kbd> （`FATFS_CODEPAGE_DYNAMIC`）时，FATFS 将支持所有代码页，但会使编译产物体积增加约 500 kB。
+  - 若选择其他代码页，请确保所选代码页与文件名字符集匹配，否则会导致乱码、无法找到文件或其他隐性问题。
 - (Top) → <kbd>Component config</kbd> → <kbd>FAT Filesystem support</kbd> → <kbd>API character encoding</kbd>
   - 本例程默认为 <kbd>API uses UTF-8 encoding</kbd> (`FATFS_API_ENCODING_UTF_8`)。
-  - 该选项会控制 FATFS API 读出的文件名所用的编码，详见该配置项的说明。
+  - 该选项控制 FATFS API 读出的文件名所使用的编码方式，详见该配置项的说明。
   - 若进行 Web 开发，建议使用 UTF 8 编码。

examples/usb/host/usb_host_msc_example/README.md

@@ -15,6 +15,19 @@ This example demonstrates how to use USB Host MSC functionality and provides a w
 
 Note: exFat requires a paid license.
 
+### FATFS Multilingual Filename Support (Enabled by Default)
+
+This demo has enabled FATFS OEM multi-code page support. To manually adjust multi-language support for filenames, please adjust the following options in menuconfig:
+
+- (Top) → <kbd>Component config</kbd> → <kbd>FAT Filesystem support</kbd> → <kbd>OEM Code Page</kbd>
+  - This example defaults to <kbd>Dynamic (all code pages supported)</kbd>.
+  - When set to <kbd>Dynamic (all code pages supported)</kbd> (`FATFS_CODEPAGE_DYNAMIC`), FATFS will support all code pages, but it will increase the size of the compiled output by about 500 kB.
+  - If you choose another code page, make sure that the selected code page matches the character set used in the filenames; otherwise it may cause garbled text, file not found errors, or other latent issues.
+- (Top) → <kbd>Component config</kbd> → <kbd>FAT Filesystem support</kbd> → <kbd>API character encoding</kbd>
+  - This example defaults to <kbd>API uses UTF-8 encoding</kbd> (`FATFS_API_ENCODING_UTF_8`).
+  - This option controls the encoding method used by the filenames read by the FATFS API. For more details, please refer to the configuration help.
+  - For web development, it is recommended to use UTF-8 encoding.
+
 ## Web Page Features
 
 - Display files and directories on the MSC device

examples/usb/host/usb_host_msc_example/README_cn.md

@@ -15,6 +15,19 @@
 
 Note: exFat 是付费许可。
 
+### FATFS 文件名多语言支持（默认启用）
+
+此 Demo 已启用 FATFS 的 OEM 多代码页支持。如需手动调整文件名的多语言支持，请在 menuconfig 中调整下列选项：
+
+- (Top) → <kbd>Component config</kbd> → <kbd>FAT Filesystem support</kbd> → <kbd>OEM Code Page</kbd>
+  - 本例程默认为 <kbd>Dynamic (all code pages supported)</kbd>。
+  - 将其设置为 <kbd>Dynamic (all code pages supported)</kbd> （`FATFS_CODEPAGE_DYNAMIC`）时，FATFS 将支持所有代码页，但会使编译产物体积增加约 500 kB。
+  - 若选择其他代码页，请确保所选代码页与文件名字符集匹配，否则会导致乱码、无法找到文件或其他隐性问题。
+- (Top) → <kbd>Component config</kbd> → <kbd>FAT Filesystem support</kbd> → <kbd>API character encoding</kbd>
+  - 本例程默认为 <kbd>API uses UTF-8 encoding</kbd> (`FATFS_API_ENCODING_UTF_8`)。
+  - 该选项控制 FATFS API 读出的文件名所使用的编码方式，详见该配置项的说明。
+  - 若进行 Web 开发，建议使用 UTF 8 编码。
+
 ## 网页功能
 
 - 显示 MSC 设备中的文件和目录

examples/usb/host/usb_host_msc_example/components/app_file_web/app_http_server.c

@@ -5,6 +5,7 @@
 
 #include <sys/param.h>
 #include <dirent.h>
+#include <ctype.h>
 #include "esp_log.h"
 #include "esp_vfs.h"
 #include "esp_http_server.h"
@@ -14,7 +15,7 @@
 #include "sdkconfig.h"
 
 /* Max length a file path can have on storage */
-#define FILE_PATH_MAX (ESP_VFS_PATH_MAX + CONFIG_SPIFFS_OBJ_NAME_LEN)
+#define FILE_PATH_MAX (ESP_VFS_PATH_MAX + CONFIG_FATFS_MAX_LFN)
 
 /* Scratch buffer size */
 #define SCRATCH_BUFSIZE  8192
@@ -46,6 +47,82 @@ struct file_server_data {
 
 static const char *TAG = "file_server";
 
+/* URL decode function to convert percent-encoded characters to their original form */
+static size_t url_decode(char *dst, const char *src, size_t dst_size)
+{
+    size_t dst_len = 0;
+    const char *src_ptr = src;
+    char *dst_ptr = dst;
+
+    while (*src_ptr && dst_len < dst_size - 1) {
+        if (*src_ptr == '%' && src_ptr[1] && src_ptr[2]) {
+            /* Check if next two characters are valid hex digits */
+            if (isxdigit((unsigned char)src_ptr[1]) && isxdigit((unsigned char)src_ptr[2])) {
+                /* Convert hex digits to character */
+                uint8_t hex1 = isdigit((unsigned char)src_ptr[1]) ? src_ptr[1] - '0' :
+                               tolower((unsigned char)src_ptr[1]) - 'a' + 10;
+                uint8_t hex2 = isdigit((unsigned char)src_ptr[2]) ? src_ptr[2] - '0' :
+                               tolower((unsigned char)src_ptr[2]) - 'a' + 10;
+
+                *dst_ptr++ = (char)((hex1 << 4) | hex2);
+                src_ptr += 3;
+                dst_len++;
+            } else {
+                /* Invalid hex sequence, copy as-is */
+                *dst_ptr++ = *src_ptr++;
+                dst_len++;
+            }
+        } else if (*src_ptr == '+') {
+            /* Convert '+' to space (mainly for query parameters, but harmless in paths) */
+            *dst_ptr++ = ' ';
+            src_ptr++;
+            dst_len++;
+        } else {
+            /* Copy character as-is */
+            *dst_ptr++ = *src_ptr++;
+            dst_len++;
+        }
+    }
+
+    *dst_ptr = '\0';
+    return dst_len;
+}
+
+/* URL encode function to convert characters to percent-encoded form for safe use in URLs */
+static size_t url_encode(char *dst, const char *src, size_t dst_size)
+{
+    size_t dst_len = 0;
+    const char *src_ptr = src;
+    char *dst_ptr = dst;
+
+    while (*src_ptr && dst_len < dst_size - 1) {
+        char c = *src_ptr;
+
+        /* Check if character needs encoding */
+        if (isalnum((unsigned char)c) || c == '-' || c == '_' || c == '.' || c == '~' || c == '/') {
+            /* Safe character, copy as-is */
+            *dst_ptr++ = c;
+            dst_len++;
+        } else {
+            /* Unsafe character, encode as %XX */
+            if (dst_len + 3 >= dst_size) {
+                /* Not enough space for encoding */
+                break;
+            }
+            uint8_t high = (c >> 4) & 0x0F;
+            uint8_t low = c & 0x0F;
+            *dst_ptr++ = '%';
+            *dst_ptr++ = (high < 10) ? ('0' + high) : ('A' + high - 10);
+            *dst_ptr++ = (low < 10) ? ('0' + low) : ('A' + low - 10);
+            dst_len += 3;
+        }
+        src_ptr++;
+    }
+
+    *dst_ptr = '\0';
+    return dst_len;
+}
+
 /* Handler to redirect incoming GET request for /index.html to /
  * This can be overridden by uploading file with same name */
 static esp_err_t index_html_get_handler(httpd_req_t *req)
@@ -162,12 +239,16 @@ static esp_err_t http_resp_dir_html(httpd_req_t *req, const char *dirpath)
         sprintf(entrysize, "%ld", entry_stat.st_size);
         ESP_LOGI(TAG, "Found %s : %s (%s bytes)", entrytype, entry->d_name, entrysize);
 
+        /* URL encode the filename for safe use in HTML href attributes */
+        char encoded_filename[CONFIG_FATFS_MAX_LFN * 3 + 1];
+        url_encode(encoded_filename, entry->d_name, sizeof(encoded_filename));
+
         /* Send chunk of HTML file containing table entries with file name and size */
         httpd_resp_sendstr_chunk(req, "<tr><td class=\"");
         httpd_resp_sendstr_chunk(req, entrytype);
         httpd_resp_sendstr_chunk(req, "\"><a href=\"");
         httpd_resp_sendstr_chunk(req, req->uri);
-        httpd_resp_sendstr_chunk(req, entry->d_name);
+        httpd_resp_sendstr_chunk(req, encoded_filename);
         if (entry->d_type == DT_DIR) {
             httpd_resp_sendstr_chunk(req, "/");
         }
@@ -178,7 +259,7 @@ static esp_err_t http_resp_dir_html(httpd_req_t *req, const char *dirpath)
         httpd_resp_sendstr_chunk(req, "</td><td>");
         httpd_resp_sendstr_chunk(req, "<button class=\"deleteButton\" filepath=\"");
         httpd_resp_sendstr_chunk(req, req->uri);
-        httpd_resp_sendstr_chunk(req, entry->d_name);
+        httpd_resp_sendstr_chunk(req, encoded_filename);
         httpd_resp_sendstr_chunk(req, "\">Delete</button>");
         httpd_resp_sendstr_chunk(req, "</td></tr>\n");
     }
@@ -217,7 +298,7 @@ static esp_err_t set_content_type_from_file(httpd_req_t *req, const char *filena
 }
 
 /* Copies the full path into destination buffer and returns
- * pointer to path (skipping the preceding base path) */
+ * pointer to path (skipping the preceding base path) with URL decoding */
 static const char *get_path_from_uri(char *dest, const char *base_path, const char *uri, size_t destsize)
 {
     const size_t base_pathlen = strlen(base_path);
@@ -232,14 +313,23 @@ static const char *get_path_from_uri(char *dest, const char *base_path, const ch
         pathlen = MIN(pathlen, hash - uri);
     }
 
-    if (base_pathlen + pathlen + 1 > destsize) {
+    /* Create temporary buffer for URL decoding */
+    char *temp_uri = alloca(pathlen + 1);
+    strlcpy(temp_uri, uri, pathlen + 1);
+
+    /* URL decode the path portion */
+    char *decoded_path = alloca(pathlen + 1);
+    size_t decoded_len = url_decode(decoded_path, temp_uri, pathlen + 1);
+
+    /* Check if full path (base + decoded path) fits in destination buffer */
+    if (base_pathlen + decoded_len + 1 > destsize) {
         /* Full path string won't fit into destination buffer */
         return NULL;
     }
 
-    /* Construct full path (base + path) */
+    /* Construct full path (base + decoded path) */
     strcpy(dest, base_path);
-    strlcpy(dest + base_pathlen, uri, pathlen + 1);
+    strcpy(dest + base_pathlen, decoded_path);
 
     /* Return pointer to path, skipping the base */
     return dest + base_pathlen;

examples/usb/host/usb_host_msc_example/components/app_file_web/spiffs/file_list_1.html

@@ -10,6 +10,11 @@
         alert('Failed to delete the file.');
         return;
       }
+      if (!enableResetButton) {
+        alert("File deleted!");
+        location.reload();
+        return;
+      }
       const cookies = document.cookie.split('; ').reduce((acc, cookie) => {
         const [name, value] = cookie.split('=');
         acc[name] = value;

examples/usb/host/usb_host_msc_example/components/app_file_web/spiffs/upload.html

@@ -124,31 +124,53 @@
     validateInputs();
   }
 
+  // Calculate UTF-8 byte length of a string
+  function getByteLength(str) {
+    return new TextEncoder().encode(str).length;
+  }
+
+  // Check for invalid filesystem characters
+  function hasInvalidPathChars(path) {
+    // Invalid characters for paths: control chars, <, >, :, ", |, ?, *, \
+    return /[\x00-\x1f<>:"|?*\\]/.test(path);
+  }
+
+  function hasInvalidFileNameChars(fileName) {
+    // Invalid characters for filenames: control chars, <, >, :, ", |, ?, *, \, /
+    return /[\x00-\x1f<>:"|?*\\/]/.test(fileName);
+  }
+
   function validateInputs() {
     const uploadPath = uploadPathInput.value;
     const fileName = fileNameInput.value;
-
+    // Validate upload path
     if (
       !uploadPath.startsWith("/") ||
       !uploadPath.endsWith("/") ||
-      /[^a-zA-Z0-9\.\/\_\-]/.test(uploadPath) ||
+      hasInvalidPathChars(uploadPath) ||
       uploadPath.startsWith("/upload/") ||
       uploadPath.startsWith("/api/") ||
-      /\/\//.test(uploadPath)
+      /\/\//.test(uploadPath) ||
+      getByteLength(uploadPath) > 255
     ) {
-      pathError.textContent = "Invalid upload path.";
+      pathError.textContent = "Invalid upload path. Path must start and end with /, contain no invalid characters, not exceed 255 bytes, and not start with /upload/ or /api/.";
     } else {
       pathError.textContent = "";
     }
-
+    // Validate file name
     if (
-      /[^a-zA-Z0-9\.\_\-]/.test(fileName) ||
-      fileName.length > 32 ||
+      hasInvalidFileNameChars(fileName) ||
+      getByteLength(fileName) > 64 ||
       fileName === "upload.html" ||
       fileName === "api" ||
-      fileName === "settings.html"
+      fileName === "settings.html" ||
+      fileName.trim() !== fileName ||
+      fileName.endsWith(".") ||
+      fileName === "" ||
+      fileName === "." ||
+      fileName === ".."
     ) {
-      nameError.textContent = "Invalid file name.";
+      nameError.textContent = "Invalid file name. Must not contain invalid characters (< > : \" | ? * \\ /), not exceed 64 bytes, and not be a reserved name.";
     } else {
       nameError.textContent = "";
     }

examples/usb/host/usb_host_msc_example/sdkconfig.defaults

@@ -2,8 +2,36 @@
 # Espressif IoT Development Framework (ESP-IDF) 5.5.0 Project Minimal Configuration
 #
 CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y
+CONFIG_WL_SECTOR_SIZE=4096
+
+#
+# FAT Filesystem support
+#
+CONFIG_FATFS_CODEPAGE_DYNAMIC=y
+CONFIG_FATFS_CODEPAGE=0
 CONFIG_FATFS_LFN_HEAP=y
+CONFIG_FATFS_MAX_LFN=255
+CONFIG_FATFS_API_ENCODING_UTF_8=y
+CONFIG_FATFS_FS_LOCK=0
+CONFIG_FATFS_TIMEOUT_MS=10000
+CONFIG_FATFS_PER_FILE_CACHE=y
+# End of FAT Filesystem support
+
 CONFIG_FATFS_USE_LABEL=y
 CONFIG_FREERTOS_HZ=1000
 CONFIG_USB_HOST_CONTROL_TRANSFER_MAX_SIZE=1024
 CONFIG_HTTPD_MAX_REQ_HDR_LEN=1024
+
+#
+# Partition Table
+#
+# CONFIG_PARTITION_TABLE_SINGLE_APP is not set
+CONFIG_PARTITION_TABLE_SINGLE_APP_LARGE=y
+# CONFIG_PARTITION_TABLE_TWO_OTA is not set
+# CONFIG_PARTITION_TABLE_TWO_OTA_LARGE is not set
+# CONFIG_PARTITION_TABLE_CUSTOM is not set
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
+CONFIG_PARTITION_TABLE_FILENAME="partitions_singleapp_large.csv"
+CONFIG_PARTITION_TABLE_OFFSET=0x8000
+CONFIG_PARTITION_TABLE_MD5=y
+# end of Partition Table