|Description||In this application note, the basic commands available for accessing a FAT16-formatted uSD card are discussed. The sample application uses the File Mount, File Open, File Write, File Read, and File Close commands to show the basics of writing to and reading from a uSD card.|
|Supported Processor||PICASO, DIABLO16|
This Application Note explores the possibilities provided by the Serial environment in Workshop for a 4D display module to work with an Arduino host. In this example, the host is an Arduino Uno board. The host can also be an Arduino Mega 2560 or Due. Ideally, the application described in this document should work with any Arduino board that supports software serial or with at least one UART serial port. See specifications of Aduino boards here.
Before getting started, the following are required:
- Any Picaso or Diablo16 display module. Visit 4dsystems.com.au to see the latest products using any of these graphics processors.
- 4D Programming Cable or µUSB-PA5
- micro-SD (µSD) memory card
- Workshop 4 IDE (installed according to the installation document)
- Any Arduino board with a UART serial port
- 4D Arduino Adaptor Shield (optional) or connecting wires
- Arduino IDE
When downloading an application note, a list of recommended application notes is shown. It is assumed that the user has read or has a working knowledge of the topics presented in these recommended application notes.
In this application note, the basic commands available for accessing a FAT16-formatted uSD card are discussed. The sample application uses the File Mount, File Open, File Write, File Read, and File Close commands to show the basics of writing to and reading from a uSD card.
The display must be configured as a slave device first before it can be controlled by a host. For instructions on how to launch Workshop 4, how to connect the display module to the PC, and how to configure the display as a slave device, kindly refer to the section “Setup Procedure” of any of the application notes below. Choose according to your display module’s processor.
These application notes also introduce the user to the Serial Protocol thru the use of the Serial Commander.
A thorough understanding of the application note Serial Connection to an Arduino Host is required before attempting to proceed further beyond this point. Serial Connection to an Arduino Host provides all the basic information that a user needs to be able to get started with the Serial Environment and Arduino. The following is a list of the topics discussed in Serial Connection to an Arduino Host.
- How to download and install the Serial-Arduino library (choose a library according to your display module’s processor)
- How to modify the library for Arduino Due (due to a Due bug reported by a forum user)
- How to define the serial port to be used for talking to the display
- How to set the baud rate
- The Error Handling Routine
- How to set the Timeout Limit
- How to reset the Arduino Host and the Display
- How to let the Display Start Up
- How to set the Screen Orientation
- How to Clear the Screen
- The uSD Card Mount Routine
- How to enable message logging to the Serial Monitor of the Arduino IDE
Discussion of any of these topics is avoided in other Serial-Arduino application notes unless necessary. Users are encouraged to read Serial Connection to an Arduino Host first.
This code starts up the FAT16 disk file services and allocates a small 20 byte control block for subsequent use. When you open a file using the “File Open” command a further 512 + 44 = 556 bytes are attached to the FAT16 file control block. When you close a file using the “File Close” command, the 556 byte allocation is released leaving the 20 byte file control block. The File Mount command must be called before any other FAT16 file related functions can be used. The control block and all FAT16 file resources are completely released with the “File Unmount” command.
The program will not continue unless a uSD card is inserted in the display.
file_Open (filename, mode)
requires two parameters. The filename parameter is the name of the file to be opened (passed as a string). The mode parameter can be any of the following:
Note: If a file is opened for write mode 'w', and the file already exists, the operation will fail.
This code creates a new text file named “SAMPLE.txt” in the uSD card. The mode is ‘w’, which means that the file is opened for writing. The File Open returns handle if file exists. The file ‘handle’ that is created is now used as reference for ‘filename’ for further file commands such as “File Close”, etc.
For File Write and File Append modes ('w' and 'a') the file is created if it does not exist. If the file is opened for append and it already exists, the file pointer is set to the end of the file ready for appending, else the file pointer will be set to the start of the newly created file.
If the file was opened successfully, the internal error number is set to 0 (i.e. no errors) and can be read with the “File Error” command. For File Read mode ('r') the file must exist else a null handle (0x00, 0x00) is returned and the 'file not found' error number is set which can be read with the “File Error” command.
This code writes a string “HELLO WORLD” to the text file “SAMPLE.txt” using file_Write(). After writing, it closes the file using file_Close(). The File Write command returns the current value of the file pointer. The File Close command will close the previously opened file.
file_Write (size, source, handle)
requires three parameters. The size parameter is the number of bytes to be written. The source parameter is string of data without null terminator. And the handle parameter is the handle that references the file to write.
requires one parameter. The parameter handle is the file handle that was created by the “File Open” command which is now used as reference ‘handle’ for the filename. The handle can be used in other file functions such as in this function - to close the file.
This code opens the file “SAMPLE.txt” previously created for reading and stores in a character array the contents of the text file using the function file_Read(). The File Read reads the number of bytes specified by "size" from the file referenced by "handle" into a destination memory buffer.
file_Read (destination, size, handle)
requires three parameters. The destination parameter is the destination memory buffer, which is a normal word-aligned address. The size parameter is the number of bytes to be read. The handle parameter is the handle that references the file to be read.
The “File Unmount” command releases any buffers for FAT16 and unmounts the Disk File System. This function is to be called to close the FAT16 file system.
After the execution of the program, the uSD card can be now be removed from the display module and can be inserted to the PC for content verification. The file “SAMPLE.txt” should be present in the uSD card.
This is the text file created by the function file_Open(). The contents of this file were written using the function file_Write(). As seen in the image below, the string that was written by the Serial Arduino program is the same as the contents of the text file.
Refer to the section “Connect the Display Module to the Arduino Host” of the application note Serial Connection to an Arduino Host for the following topics:
- Using the New 4D Arduino Adaptor Shield (Rev 2.00)
- Definition of Jumpers and Headers
- Default Jumper Settings
- Change the Arduino Host Serial Port
- Power the Arduino Host and the Display Separately
- Using the Old 4D Arduino Adaptor Shield (Rev 1)
Connection Using Jumper Wires