File System
A complete FAT file system is a built in the DUELink firmware. It includes, FAT16, FAT32, Long-File-Name (LFN), directory handling, and several file-processing functions. It is limited to 2 GBytes size files! Thanks to Elm Chan for the awesome open-source FAT library.
Mount
Mount and initialize the file system. Only one media is supported at any given time.
| Function | Description |
|---|---|
FsMnt(type, cs, baud, max_handle) | Enable file system to a specific type of media on SPI bus with cs chip-select pin at baud KHz, with maximum allowed file handles max_handle. Returns 0 if success. |
FsUnMnt() | Release file system. Returns 0 if success. |
FsFmt(type, cs, baud) | Format the mounted media. Note that this takes several minutes to complete. |
Supported media types:
| ID | Type |
|---|---|
| 0 | Reserved |
| 1 | SD or Micro SD cards (includes SDHC) |
| 2 | USB |
File Operations
Unless otherwise stated, all functions return 0 or positive for error code (error code 0: success), or negative on failure.
| Function | Description |
|---|---|
FsOpen("path", mode) | Returns a file handle on success. 0 or negative on failure. |
FsClose(handle) | Close file and release handle. |
FsWrite(handle, [data]) | Write from data array. Returns how many bytes were write, negative error code otherwise. |
FsRead(handle, [data]) | Read into data array. Returns how many bytes were read, negative error code otherwise. |
FsSync(handle) | Sync file with any buffered data. |
FsSeek(handle, offset) | change the location in the handle file on where to read or write. |
FsTell(handle) | Returns the current location being access in handle file. |
FsDel("path") | Delete file or directory at path. |
FsFind("path") | Find if existing name is available. Returns the item type if found, return 0x10 for directory, 0x20 for file for example. |
fsfsz("path") | Returns path file size, negative number on failure. |
File Open Modes
| ID | mode |
|---|---|
| 0x01 | Read only |
| 0x02 | Write only |
| 0x00 | Open existing. Require existing file, or return -1 |
| 0x04 | Create new. Require NOT existing file, or return -1 |
| 0x08 | Create always. Force create new. If file is already exit, it will be deleted for new file |
| 0x30 | Open append. If not exist, create one |
Combine multiple modes, like use FsOpen("/test.txt", 0x02|0x0x30) to open a file for write and append if existing.
Directory Operations
| Function | Description |
|---|---|
FsMkDir("path") | Create a new directory at path. |
FsOpDir("path") | Open a directory at path. |
FsFNext([name], [type]) | Finds the next item and fills in name with the next file or directory it found in an open directory using FsOpDir(). type is a single byte array containing the item type in standard FAT file system format, for example [0x10] for directly and [0x20] for files. |
# file open types
_r = 0x01 # Read only
_w = 0x02 # Write only
_x = 0x00 # Open existing. Require existing file, or return -1
_n = 0x04 # Create new. Require NOT existing file, or return -1
_c = 0x08 # Create always. Force create new. If file is already exit, it will be deleted for new file.
_a = 0x30 # Open append. If not exist, create one.
Dim b1[] = "Hello World"
# SD card, pin 17 chip select, 8Mhz clock, 4 file handles max
fsmnt(1, 17, 8000, 4)
# Write b1 array to a file
h = FsOpen("/test.txt", _w|_c)
FsWrite(h, b1)
FSClose(h)
# Read from the same file to b2 array
h = FsOpen("/test.txt", _r)
Dim b2[11]
FsRead(h, b2)
Println(b2)
FSClose(h)
fsunmnt()
USB Memory Drives
Accessing files on USB thumb drives is dome exactly same as SD. Type 2 media is USB memory. The second and third arguments are ignored in USB host mode.
# USB thumbdrive, 4 file handles max
fsmnt(2, 0, 0, 4)
The use of USB Host requires a special co-processor, which is already included on modules such as USB Host.