在嵌入式开发中，FatFs因其良好的可移植性和低资源占用而备受青睐。其核心功能之一是全面支持FAT32文件系统，使得设备能够无缝读写大容量存储介质，满足现代物联网与智能硬件对数据存储的高要求。
一、概述
fatfs库提供了对FAT32文件系统的支持，主要用于读写TF卡、SD卡等外部存储设备。
1.1 存储系统概述
LuatOS的存储系统采用清晰的分层架构设计，其核心目标是为应用层提供统一、简洁的文件操作接口，从而屏蔽底层不同存储介质和文件系统的差异。开发者无需关心数据具体存储在何种硬件上，也无需关心底层文件系统的具体实现，只需调用统一的API即可完成文件操作。
该系统的层次结构与各组件间的协作关系如下图所示，其数据流与依赖关系自上而下贯穿各层：
1.1.1 物理硬件层
这是数据存储的物理载体，LuatOS支持多种常见的嵌入式存储硬件：
1、SPI/SDIO TF卡：通过高速SPI或SDIO接口连接的块存储设备，特点是容量大、可插拔，适用于存储大量数据（如音频、图片文件）；
2、SPI NOR Flash：通过SPI接口访问的NOR型闪存。其特点是读写速度快，通常用于存放固件代码或需要快速读写的关键数据；
3、SPI NAND Flash：通过SPI接口访问的NAND型闪存。其特点是容量大、成本低，适用于存储日志等容量需求较大的数据；
1.1.2 文件系统实现层**(fatfs&lf)**
文件系统负责管理存储设备的空间，组织文件和目录结构。LuatOS根据硬件特性，适配了两种主流的嵌入式文件系统：
1、FATFS：一个兼容FAT12/FAT16/FAT32标准的通用文件系统。它通常与SD/TF卡配对使用，；
2、LFS(LittleFS)：它通常与SPI NOR Flash和SPI NAND Flash配对使用，非常适合在裸Flash设备上运行；
1.1.3 统一API层 (io)
fs库不推荐新用户使用，该库仅对已经使用过的老用户进行保留，其功能已经完全移植到io库中，且更加完善，新用户建议都参考io核心库：
1、fs 库：提供文件系统的额外操作。不建议使用，请使用io库进行替代；
2、io 库：提供标准的数据流操作接口，用于文件的打开、读写、关闭等，是处理文件内容的主要手段，包含fs库的所有功能，推荐使用；
1.1.4 应用层(luatOS应用脚本)
用户通过调用io库，fatfs库，lf库以及fs库中的api接口，来实现自己的业务逻辑。
1.1.5 推荐使用
对于FAT文件系统需求，使用 fatfs 库。
对于文件内容操作需求，使用 io 库。
1.2 本文中扇区 (Sector) 的概念
扇区：存储设备，如TF卡、硬盘等外部存储设备中最小的信息管理单位；
1.2.1 物理层面 (最根本的定义)
1、扇区是存储设备（如TF卡、SD卡、硬盘、U盘）能够进行读写操作的最小物理单元；
2、这是由硬件制造商决定的，对于绝大多数现代存储设备，这个大小被固定为 512字节；
3、这意味着，即使您只想在文件中保存1个字节的数据（比如一个字母'A'），存储设备实际上也必须读写整整一个扇区（512字节）；
1.2.2 逻辑/软件层面
1、操作系统和文件系统（如FAT32，也就是FatFS操作的对象）在此基础上建立了更高级的管理结构；
2、文件系统会将多个扇区组合成一个"簇" (Cluster) 或"块" (Block) 来进行文件管理，以提高效率；
1.2.3 如何计算总容量
既然1个扇区 = 512字节，那么：
总容量计算：
总容量 (字节) = total_sectors * 512
总容量 (KB) = total_sectors * 512 / 1024 = total_sectors / 2
二、核心示例
1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
三、常量详解
核心库常量，顾名思义是由 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；
每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；
如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；
3.1 fatfs.SPI(SPI模式)
3.2 fatfs.SDIO(SDIO模式)
四、函数详解
4.1 fatfs.mount(mode, mount_point, spiid_or_spidevice, spi_cs, spi_speed, power_pin, power_on_delay, auto_format)
功能
挂载FAT文件系统；
注意事项
1、挂载前需确保SPI接口已正确初始化，SDIO模式不需要初始化； 2、若挂载失败，可以尝试打开调试信息查找原因；
参数
mode
mount_point
spiid_or_spidevice
spi_cs
spi_speed
power_pin
power_on_delay
auto_format
返回值
local success, err = fatfs.mount(mode, mount_point, spiid_or_spidevice, spi_cs, spi_speed, power_pin, power_on_delay, auto_format)
有两个返回值success和err
success
err
错误返回码对照表
错误返回值对照表
示例
4.2 fatfs.unmount(mount_point)
功能
取消挂载fatfs文件系统；
注意事项
1、必须与fatfs.mount的挂载点参数一致；
2、卸载前应确保所有文件操作已完成；
参数
mount_point
返回值
local result = fatfs.unmount(mount_point)
有一个返回值 result
result
示例
4.3 fatfs.getfree(mount_point)
功能
获取文件系统可用空间信息；
注意事项
1、当前扇区大小固定在512字节；
2、需要跟fatfs.mount传入的挂载点一致；
参数
mount_point
返回值
local data, err = fatfs.getfree(mount_point)
有两个返回值data和err
data
err
错误返回码对照表
示例
4.4 fatfs.debug(value)
功能
设置fatfs调试模式；
注意事项
建议仅在排查问题时开启，增加调试日志；
参数
value
返回值
无
示例
4.5 fatfs.config(crc_check, write_to)
功能
配置fatfs特殊参数；
注意事项
1、大部分卡无需配置；
2、部分不能正常读写的卡，经过配置后可能能读写成功（暂未有实际案例）；
参数
crc_check
write_to
返回值
无
示例
五、模组支持说明
支持 LuatOS 开发的所有模组都支持fatfs核心库。
今天的内容就分享到这里了~