Component: FAT (SD, SDHC) (Storage)

Author	Matrix Ltd.
Version	2.7 (Release)
Category	Storage

FAT (SD, SDHC) component

FAT component allowing access to read and write files on a SD, SDHC or MMC card.

The component automatically detects the filesystem on the card on initialise so FAT16 and FAT32 are fully supported.

Examples

Reading data from a text file

Example to read a text file from a SD card or from a text file in simulation and display on a 16 x 2 character LCD. The text file needs to be in the same directory as the Flowcode .fcfx project file for the simulation to run correctly. FAT Read File File:Test.txt

Console showing current 512 byte sector data

Console showing high level FAT status

Parsing a standard .BMP image file

Example to read a bitmap image file from a SD card or from a bitmap file in simulation and display on a graphical LCD. The bitmapfile needs to be in the same directory as the Flowcode .fcfx project file for the simulation to run correctly. FAT display Bitmap Demo bitmap files referenced in the example.

File:FATDemoBitmaps.zip

Picture showing a bitmap being displayed on a GLCD component.

Data logger Simple

Example showing how to take a collection of analogue readings and save them into a text based file, the simple way. FAT data logger simple but slow

Data logger Advanced

Example showing how to take a collection of analogue readings and save them into a text based file, the fast way. FAT data logger fast

Log Keypad Presses

Example showing how to poll a keypad for key presses. Each key press is shown on an LCD and appended to a log file as an ASCII character using the FAT component. Keypad Press Log

Streaming Audio Files

Example showing how to steam out .wav audio files from an SD card using a 16-bit @ 16KHz file format. A free program such as Audacity can be used to create or edit the .wav files. WAV Streaming

Downloadable macro reference

ReadStringFromFile

Reads a string from the currently open file. Auto increments the position in the file.

An empty string signifies the end of the file has been reached.

Parameters

BYTE NumBytes

Maximum number of bytes to attempt to read

BYTE EndChar

Ends the string if the value specified is found, default is 0

Return value

STRING

WriteByteToBuffer

Writes a single byte to the current 512 byte local sector buffer.

Parameters

UINT Address

Address Range 0 - 511

BYTE Data

Data Byte to write to the buffer

Return value

This call does not return a value

MoveToNextFileSector

Attempts to move to the next sector in the file.

When reading a file you would leave force next sector set to 0.

When writing a file you would leave force next sector set to 1 to allow new sectors to be created as the file grows.

Returns 0 for success

Parameters

BYTE Force_Next_Sector

0 = Don't add new sector, 1 = Add new sector if we are at the end of the file

Return value

BYTE

AppendByteToFile

Adds a single byte to the end of the currently open file, useful for inserting the value 0 into binary file types.

Returns 0 for success.

Parameters

<- BYTE Data

Data to append to the end of the file

This parameter may be returned back to the caller

Return value

BYTE

ReadFileSector

Overwrites local buffer with the current file sector from the disk.

Used to restore the local sector buffer with the actual sector stored on the card.

Return = 0 : Local buffer refreshed with current card sector

Return > 0 : Error

Parameters

This macro has no parameters

Return value

BYTE

ReadByteFromFile

Reads a byte from the currently open file. Auto increments the position in the file.

A return value of 0 may signify the end of the file has been reached (depending on the contents of the file).

Parameters

This macro has no parameters

Return value

UINT

DeleteFile

Searches for and deletes a file in the current folder location on the card. Default = Root

Returns 0 for success.

Parameters

<- STRING Filename

8.3 format filename e.g."file.txt"

This parameter may be returned back to the caller

Return value

BYTE

CreateFile

Creates a file in the current folder location on the card. Default = Root

Returns 0 for success

File must be opened using "Open_File" after creation before writing any data.

Parameters

<- STRING Filename

8.3 format filename e.g."file.txt"

This parameter may be returned back to the caller

Return value

BYTE

ScanCurrentFolder

Method for retreiving file or folder names for the card to allow for dynamic file opening or playback. Does not currently simulate.

0 - Filetype found and stored into string array, 1 - End of folder reached, 2 - Filetype mismatch 3 - Empty

Parameters

UINT Current_Idx

Contains the current pointer in the directory table. Values from 0 to 511 to completley search the current folder for a files or folders

BYTE Scan_Type

Sets the scan to search for Files or Folders. 0 = Scan for files, 1 = Scan for folders

Return value

BYTE

ReadByteFromScan

Returns a byte of the name of the file or folder retreived from the Scan_Current_folder function.

Return = ASCII byte at position Idx from the folder name or file name at position Current_Idx in the directory

Parameters

BYTE idx

0 - 11 for a file, 0 - 7 for a folder

Return value

BYTE

OpenFolder

".." - Jumps up a directory, if at root then remains in root

"root" - Jumps directly back to the root directory

"foldername" - Opens folder named foldername

Parameters

<- STRING Folder_Name

This parameter may be returned back to the caller

Return value

BYTE

ReadByteFromBuffer

Reads a byte of data from the local sector buffer.

Return = Data byte read from the local sector buffer.

Parameters

UINT Address

0 - 511 - Contains the position of the byte to be read

Return value

BYTE

ReadFileLength

Returns the number of bytes in the current sector that are used by the current open file.

Return = 512 - Sector is filled with file data

Return < 512 - Last sector of the file, Retval specifies how many bytes of data are remaining in the sector

Parameters

This macro has no parameters

Return value

INT

OpenFile

Searches for and opens a file for reading or writing from within the current directory on the disk.

Returns 0 for success.

Parameters

<- STRING Filename

8.3 filename of the file we are trying to open e.g. "file.txt"

This parameter may be returned back to the caller

Return value

BYTE

WriteFileSector

Overwrites the current sector on the memory card with the contents of the local sector buffer. See write_byte_to_buffer function.

Return = 0 - File sector written successfully.

Return > 0 - File sector write error

Parameters

This macro has no parameters

Return value

BYTE

SetFileIndex

Sets the current file index and used to switch between several open file streams.

Default = 0.

Parameters

BYTE File_Index

File index ranges from 0 to (Max Concurrent Files - 1)

Return value

This call does not return a value

AppendStringToFile

Adds the contents of the data string parameter to the end of the currently open file.

Returns 0 for success.

Parameters

<- STRING Data_String

Data to append to the end of the file

This parameter may be returned back to the caller

Return value

BYTE

SetTimeAndDate

Sets the current time and date.

Time = (Hour << 11) + (Min << 5) + (Sec >> 1)

Date = (YearFrom1980 << 9) + (Month << 5) + (Day)

Additional details can be found here: http://www.maverick-os.dk/FileSystemFormats/FAT16_FileSystem.html#TimeFormat

Parameters

UINT Time

Sets the current Time in FAT Time format hhhhhmmmmmmsssss - S=Secs/2

UINT Date

Sets the current Date in FAT Date format yyyyyyymmmmddddd - Y=Years since 1980

Return value

This call does not return a value

Initialise

Attempts to communicate with the SD card and if successful sets up the file system.

Returns 0 for success.

Parameters

This macro has no parameters

Return value

BYTE

Simulation macro reference

This component does not contain any simulation macros

Property reference

Max Concurrent Files

This property is of type Signed integer and can be referenced with the variable name max_concurrent_files.

Specifies how many concurrent files can be opened at any one time.

Use the SetFileIndex macro to switch between concurrent files.

End Of File

This property is of type Fixed list of ints and can be referenced with the variable name EOFtype.

Specifies the way the ReadByteFromFile function indicates the end of a file.

8 Bit mode - End of the file is represented by the value 0, read multiple times to confirm that the 0 is not simply data.

16 Bit mode - End of file is represented by the value 512 allowing the values 0 - 255 to represent valid data.

Channel

This property is of type Fixed list of ints and can be referenced with the variable name Channel.

SPI communications channel

Initial Prescaler

This property is of type Fixed list of ints and can be referenced with the variable name PR_SCALE.

SPI initial clock divider - Frequency should be under 400khz to allow startup to work correctly.

High Speed Prescaler

This property is of type Fixed list of ints and can be referenced with the variable name PR_SCALE2.

SPI high speed clock divider - Once startup is complete this is the rate that will be used to transfer data

Chip Select - CS

This property is of type Single digital pin and can be referenced with the variable name cs_pin.

Chip Select Pin for SPI

Data Out - MOSI / SDO

This property is of type Single digital pin and can be referenced with the variable name mosi_pin.

Data Out SPI Pin

Data In - MISO / SDI

This property is of type Single digital pin and can be referenced with the variable name miso_pin.

Data In SPI Pin

Serial Clock - SCK

This property is of type Single digital pin and can be referenced with the variable name sck_pin.

Master Clock SPI pin

Root Directory

This property is of type Directory and can be referenced with the variable name root_dir.

Directory flagged as root for simulation.

Modern windows systems do not like you writing files to a hard drive root directory so a directory off the root is advised.

Auto Insert Card

This property is of type True or false and can be referenced with the variable name AutoInsertCard.

When set to yes the SD card will be automatically inserted at the start of simulation,

Otherwise you must manually click the card on the panel to insert.