View source for Component: File (SD, SDHC) (Storage)



{| width="50%"
|-
| width="20%" style="color: gray;" | Author
| Matrix Ltd.
|-
| width="20%" style="color: gray;" | Version
| 3.0 (Release)
|-
| width="20%" style="color: gray;" | Category
| Storage
|}



==[[File:Component Icon 0b61bd39_05a3_46ee_a2a5_da7bffb583c5.png|Image]] File (SD, SDHC) component==
File 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.
{{Fcfile|FAT Read_File.fcfx|FAT Read File}}
[[File:test.txt]]


Console showing current 512 byte sector data

[[File:FatBuffer.jpg]]


Console showing high level FAT status

[[File:FatStatus.jpg]]


===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.
{{Fcfile|GLCD_FAT_BMP.fcfx|FAT display Bitmap}}
Demo bitmap files referenced in the example.

[[File:FATDemoBitmaps.zip]]


Picture showing a bitmap being displayed on a GLCD component.

[[File:FatSimulatedBitmap.jpg]]


===Data logger Simple===

Example showing how to take a collection of analogue readings and save them into a text based file, the simple way.
{{Fcfile|FAT Data_Logger_Simple_Slow.fcfx|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.
{{Fcfile|FAT Data_Logger_Fast.fcfx|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.
{{Fcfile|Keypad2FAT.fcfx|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.
{{Fcfile|WAV_Streaming.fcfx|WAV Streaming}}

==Downloadable macro reference==

===<span style="font-weight: normal;"><u><tt>ReadStringFromFile</tt></u></span>===
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'''

:[[Variable Types|BYTE]] ''NumBytes''
::Maximum number of bytes to attempt to read

:[[Variable Types|BYTE]] ''EndChar''
::Ends the string if the value specified is found, default is 0


'''Return value'''

:[[Variable Types|STRING]]


===<span style="font-weight: normal;"><u><tt>WriteByteToBuffer</tt></u></span>===
Writes a single byte to the current 512 byte local sector buffer.

'''Parameters'''

:[[Variable Types|UINT]] ''Address''
::Address Range 0 - 511

:[[Variable Types|BYTE]] ''Data''
::Data Byte to write to the buffer


'''Return value'''

:''This call does not return a value''


===<span style="font-weight: normal;"><u><tt>MoveToNextFileSector</tt></u></span>===
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'''

:[[Variable Types|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'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>AppendByteToFile</tt></u></span>===
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'''

:[[Variable Types|<- BYTE]] ''Data''
::Data to append to the end of the file
::''This parameter may be returned back to the caller''


'''Return value'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>ReadFileSector</tt></u></span>===
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'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>ReadByteFromFile</tt></u></span>===
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'''

:[[Variable Types|UINT]]


===<span style="font-weight: normal;"><u><tt>DeleteFile</tt></u></span>===
Searches for and deletes a file in the current folder location on the card. Default = Root

Returns 0 for success.

'''Parameters'''

:[[Variable Types|<- STRING]] ''Filename''
::8.3 format filename e.g."file.txt"
::''This parameter may be returned back to the caller''


'''Return value'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>ReadByteFromIndex</tt></u></span>===
Reads an arbitrary byte of data from the current open file.



Return = Data byte read from the local sector buffer. 



Experimental and potentially slow if navigating backwards through the file.

'''Parameters'''

:[[Variable Types|ULONG]] ''Address''
::Contains the position of the byte to be read from the file


'''Return value'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>CreateFile</tt></u></span>===
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'''

:[[Variable Types|<- STRING]] ''Filename''
::8.3 format filename e.g."file.txt"
::''This parameter may be returned back to the caller''


'''Return value'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>ScanCurrentFolder</tt></u></span>===
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'''

:[[Variable Types|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

:[[Variable Types|BYTE]] ''Scan_Type''
::Sets the scan to search for Files or Folders. 0 = Scan for files, 1 = Scan for folders


'''Return value'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>ReadByteFromScan</tt></u></span>===
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'''

:[[Variable Types|BYTE]] ''idx''
::0 - 11 for a file, 0 - 7 for a folder


'''Return value'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>OpenFolder</tt></u></span>===
".." - 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'''

:[[Variable Types|<- STRING]] ''Folder_Name''
::''This parameter may be returned back to the caller''


'''Return value'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>ReadByteFromBuffer</tt></u></span>===
Reads a byte of data from the local sector buffer.

Return = Data byte read from the local sector buffer.

'''Parameters'''

:[[Variable Types|UINT]] ''Address''
::0 - 511 - Contains the position of the byte to be read


'''Return value'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>ReadFileLength</tt></u></span>===
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'''

:[[Variable Types|INT]]


===<span style="font-weight: normal;"><u><tt>OpenFile</tt></u></span>===
Searches for and opens a file for reading or writing from within the current directory on the disk.

Returns 0 for success.

'''Parameters'''

:[[Variable Types|<- 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'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>WriteFileSector</tt></u></span>===
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'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>SetFileIndex</tt></u></span>===
Sets the current file index and used to switch between several open file streams. 

Default = 0.

'''Parameters'''

:[[Variable Types|BYTE]] ''File_Index''
::File index ranges from 0 to (Max Concurrent Files - 1)


'''Return value'''

:''This call does not return a value''


===<span style="font-weight: normal;"><u><tt>AppendStringToFile</tt></u></span>===
Adds the contents of the data string parameter to the end of the currently open file.

Returns 0 for success.

'''Parameters'''

:[[Variable Types|<- STRING]] ''Data_String''
::Data to append to the end of the file
::''This parameter may be returned back to the caller''


'''Return value'''

:[[Variable Types|BYTE]]


===<span style="font-weight: normal;"><u><tt>SetTimeAndDate</tt></u></span>===
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'''

:[[Variable Types|UINT]] ''Time''
::Sets the current Time in FAT Time format hhhhhmmmmmmsssss - S=Secs/2

:[[Variable Types|UINT]] ''Date''
::Sets the current Date in FAT Date format yyyyyyymmmmddddd - Y=Years since 1980


'''Return value'''

:''This call does not return a value''


===<span style="font-weight: normal;"><u><tt>Initialise</tt></u></span>===
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'''

:[[Variable Types|BYTE]]



==Simulation macro reference==

''This component does not contain any simulation macros''


==Property reference==
<span style="font-weight: normal;"><u>Channel</u></span>

This property is of type ''Fixed list of ints'' and can be referenced with the variable name ''cal_spi::CHANNEL''.

SPI Channel selector

<span style="font-weight: normal;"><u>MOSI</u></span>

This property is of type ''Single digital pin'' and can be referenced with the variable name ''cal_spi::MOSI''.

SPI Data Out Pin SDO - Also Known as Master Out Slave In (MOSI) when used in Master mode.

<span style="font-weight: normal;"><u>MISO</u></span>

This property is of type ''Single digital pin'' and can be referenced with the variable name ''cal_spi::MISO''.

SPI Data In Pin SDI - Also Known as Master In Slave Out (MISO) when used in Master mode.

<span style="font-weight: normal;"><u>CLK</u></span>

This property is of type ''Single digital pin'' and can be referenced with the variable name ''cal_spi::CLK''.

SPI Clock Pin CLK - The Clock signal is driven by the SPI master.

<span style="font-weight: normal;"><u>CS / SS</u></span>

This property is of type ''Single digital pin'' and can be referenced with the variable name ''cal_spi::SS''.

Chip Select / Slave Select Pin 

Master Mode: General purpose output pin used to select the remote SPI device.

Slave Mode: Hardware chip select pin input used to select the SPI device.

<span style="font-weight: normal;"><u>Initial Prescaler</u></span>

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.

<span style="font-weight: normal;"><u>High Speed Prescaler</u></span>

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

<span style="font-weight: normal;"><u>Max Concurrent Files</u></span>

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.

<span style="font-weight: normal;"><u>End Of File</u></span>

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.

<span style="font-weight: normal;"><u>Auto Insert Card</u></span>

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 or remove.

<span style="font-weight: normal;"><u>Sim Type</u></span>

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

Defines the simulation type.

The default is to use the Windows file system to allow for reading and writing files.

The alternative is to use the CAL functionality to allow the SPI transactions to be passed onto a seperate handler e.g. for logging or debugging purposes.

<span style="font-weight: normal;"><u>Root Directory</u></span>

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

Directory flagged as root for simulation Default: $(srcdir) is the current project source directory.



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

<span style="font-weight: normal;"><u>Scope Traces</u></span>

This property is of type ''True or false'' and can be referenced with the variable name ''cal_spi::ScopeTraces''.

Selects if the scope traces are automatically generated or not

<span style="font-weight: normal;"><u>Console Data</u></span>

This property is of type ''True or false'' and can be referenced with the variable name ''cal_spi::ConsoleData''.

Selects if the console data is automatically generated or not

<span style="font-weight: normal;"><u>Injector</u></span>

This property is of type ''Fixed list of ints'' and can be referenced with the variable name ''cal_spi::Injector''.

''<span style="color:red;">No additional information</span>''