R/W FAT FS in SD/MMC Cards

The FAT file system

The FAT file system implementation in eLua uses Elm Chan's excellent FatFS package, available here. It can handle FAT12, FAT16 and FAT32 file systems in read/write mode, and it packs a lot of functionality in a low footprint. Like the ROM filesystem it is integrated with the C library, so similar POSIX file manipulation will work in addition to accessing the filesystem via the Lua io module. eLua adds a platform abstraction layer on top of FatFS which makes it very easy to port the FAT file system implementation between different eLua targets. Since most SD/MMC cards can be accessed using the very common SPI interface, and since eLua already provides a SPI platform interface, porting the FAT file system to an eLua board is a fairly simple process.

To use the FAT file system on your elua board (that has the proper hardware to access SD/MMC cards), first make sure that there is a working implementation of the eLua SPI platform interface on your platform (as currently eLua can access SD/MMC cards only via SPI). Then you need to enable the FAT file system module (MMCFS) in your eLua binary image, as described on the building page.

Using the FAT file system

To use the FAT filesystem with an SD or MMC card, first ensure that the card has been properly formatted as a FAT filesystem (many come preformatted with this file system).

Next, ensure that you have connected the SD or MMC card using the pin configuration described in the table below. For more more information, see Elm Chan's page on SD/MMC with SPI.

eLua PIN Static Config SD Card Pin MMC Card Pin
CS MMCFS_CS_PORT,
MMCFS_CS_PIN
DAT3/CS RES/CS
SPI DO MMCFS_SPI_NUM CMD/DI CMD/DI
SPI DI MMCFS_SPI_NUM DAT0/DO DAT0/DO
SPI SCLK MMCFS_SPI_NUM CLK CLK

New in 0.9: it's possible to use more than one SD card on your eLua board. Refer to building page for more details.


Once configured, connected, and eLua has started up, you are ready to work with the files on your card. To open a file on the SD/MMC card, all you need to do is to prefix its name with /mmc/, like this:

# lua /mmc/info.lua 

Similarly, if you wanted to access a text file a.txt from your card, you could use fopen like this:

f = fopen( "/mmc/a.txt", "rb" )

New in 0.9: if more than one SD card is configured in the system, their corresponding names will end with a single digit that specifies the card ID in the system (/mmc0, /mmc1 and so on).