Facebook Pixel

AN-00161 ViSi-Genie Magic How to Read a File

Description In the past it was not possible for a host to access files stored in the uSD card of a display module loaded with a ViSi-Genie application. With Workshop 4 Pro it is now possible to accomplish this through the use of the Magic Object. The Magic Object is one of the objects available under the Genie Magic pane. It is actually a 4DGL function which allows users to program the display to handle bytes received from an external host. The user, for instance, can create a Magic Object that waits for 14 bytes from the host. The 14 bytes can contain an instruction byte, followed by a null-terminated 8.3 format filename (e.g. "datalog1.txt"). The instruction byte can be a file read, a file write, a file append, etc. Upon receiving a file read instruction together with the filename, for example, the display module will send back the contents of the file (if it exists) to the host. The ViSi-Genie example project “FileAccess.4DGenie” is an example of the above application.
Supported Processor PICASO, DIABLO16
Supported Environment ViSi-Genie
Difficulty Medium

 

File Downloads
Documentation
Files

Description

This application note primarily shows how the Magic Object is used to implement a ViSi-Genie project that allows the host to access files on the uSD card of the display. There are seven types of file access operations: 

  1. MFILE_READ
  2. MFILE_WRITE
  3. MFILE_APPEND
  4. MFILE_ERASE
  5. MFILE_DIR
  6. MFILE_SCREEN_CAPTURE
  7. MFILE_SIZE

For this application note, the file access operation “MFILE_READ” is discussed. The implementation of a file read operation further requires the use of the following 4DGL features and functions in combination with the Magic Event object:

  • String class functions
  • FAT16 file functions
  • seroutCS(…)

The String class functions and FAT16 file functions are functions native to the Picaso and Diablo16 processors. 

The function seroutCS(…) is one of the Genie Magic callable functions in the ViSi-Genie Communications Protocol. This function writes a parameter to the Genie Serial port and updates the output checksum.

 

Below is a screenshot image of the project used in this application note.

 

Note 1: The ViSi-Genie project for this application note is the demo “FileAccess”, which is found in Workshop. Go to the File menu -> Samples -> ViSi Genie Magic (Picaso/Diablo16) -> FileAccess.4DGenie.

Note 2: Workshop Pro is needed for this application.

 

Before getting started, the following are required:

and other superseded modules which support the ViSi Genie environment

Visit www.4dsystems.com.au/products to see the latest display module products that use the Diablo16 processor.

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.

 

Application Overview

In the past it was not possible for a host to access files stored in the uSD card of a display module loaded with a ViSi-Genie application. With Workshop 4 Pro it is now possible to accomplish this through the use of the Magic Object. The Magic Object is one of the objects available under the Genie Magic pane. It is actually a 4DGL function which allows users to program the display to handle bytes received from an external host. The user, for instance, can create a Magic Object that waits for 14 bytes from the host. The 14 bytes can contain an instruction byte, followed by a null-terminated 8.3 format filename (e.g. "datalog1.txt"). The instruction byte can be a file read, a file write, a file append, etc. Upon receiving a file read instruction together with the filename, for example, the display module will send back the contents of the file (if it exists) to the host. The ViSi-Genie example project “FileAccess.4DGenie” is an example of the above application.

 

Setup Procedure

For instructions on how to launch Workshop 4, how to open a ViSi-Genie project, and how to change the target display, kindly refer to the section “Setup Procedure” of the application note:

ViSi Genie Getting Started – First Project for Picaso Displays (for Picaso)

or

ViSi Genie Getting Started – First Project for Diablo16 Displays (for Diablo16).

 

Create a New Project

Create a New Project

For instructions on how to create a new ViSi-Genie project, please refer to the section “Create a New Project” of the application note

ViSi Genie Getting Started – First Project for Picaso Displays (for Picaso)

or

ViSi Genie Getting Started – First Project for Diablo16 Displays (for Diablo16).

 

Design the Project

Add Two Static Text Objects to Form0

Two static text objects are added to Form0. These are Statictext0 and Statictext1.

 

To know more about static text objects, their properties, and how they are added to a project, refer to the application note

ViSi-Genie Labels, Text, and Strings

 

Add a Magic Object to Form0

A Magic Object is added to Form0. This is MagicObject0.

 

To know more about Magic Objects, their properties, and how they are added to a project, refer to the application note

ViSi-Genie How to Add Magic Objects

 

Model

File Access Operations

Below is a general model for an application that performs file access operations.

 

The WRITE_MAGIC_BYTES and REPORT_MAGIC_EVENT_BYTES messages or commands are two complementary messages that are used in ViSi-Genie Magic.  The host sends a WRITE_MAGIC_BYTES message, and the display module, after performing the requested operation, replies with a REPORT_MAGIC_EVENT_BYTES message. Steps 2 and 3 can be implemented using a Magic Object.

 

File Read

Below is a model specific to an application that performs a file read operation.

 

Section 5.4 (Genie Magic File Access object) of the ViSi-Genie Reference Manual documents the seven file operations implemented in the example project “FileAccess.4DGenie”. For this application note, will take look at MFILE_READ.

 

WRITE_MAGIC_BYTES

The standard format of WRITE_MAGIC_BYTES message, as defined in section 2.1.2 (Command and Parameters Table) of the ViSi-Genie Reference Manual is:

 

Section 5.4 (Genie Magic File Access object) of the ViSi-Genie Reference Manual describes the WRITE_MAGIC_BYTES message for a file read operation (as expected by FileAcces.4DGenie).

 

Thus, a WRITE_MAGIC_BYTES message specific to a file read operation, has the format:

 

Let us look at two examples of a WRITE_MAGIC_BYTES message sent from a host to the display for a file read operation.

To read the contents of the file “notexist.txt”, the host would send:

 

To read the contents of the file “data.log”, the host would send:

 

REPORT_MAGIC_EVENT_BYTES

The standard format of REPORT_MAGIC_EVENT_BYTES message, as defined in section 2.1.2 (Command and Parameters Table) of the ViSi-Genie Reference Manual is:

 

Section 5.4 (Genie Magic File Access object) of the ViSi-Genie Reference Manual states that a REPORT_MAGIC_EVENT_BYTES message for a file read operation, as implemented in FileAcces.4DGenie, will have the following additional data.

 

File Read Error

If an error occurs during the file read operation (e.g. the file to be read does not exist), an empty or null REPORT_MAGIC_EVENT_BYTES message is sent back by the display module. The message will contain only the command byte for file read. For example, if the file “notexist.txt” does not exist, the display module would reply with the message shown below, followed by an acknowledgment byte (ACK).

 

Small Files

For this case we assume that the text file “data.log” exists on the uSD card of the display module. This text file contains a short string less than 253 bytes long.

 

The display module would reply with the message shown below, followed by an acknowledgment byte (ACK).

 

 

Large Files

For a more reliable data transfer, the contents of a large file being read are divided into packets, each of which is 253 bytes long. Each packet is then inserted into a REPORT_MAGIC_EVENT_BYTES message. To illustrate the case for data transfer of large files, we assume that the file “ascii.txt” exists on the uSD card. This file contains alphanumeric characters and is 318 bytes long.

 

The contents of the file will be divided into two packets. The first packet is 253 bytes long, and the second is 65 bytes long. To illustrate,

 

Large Files – 1st Packet

Note that the screenshot image of the message was cropped.

 

Large Files – 2nd Packet

Note that the screenshot image of the message was cropped.

 

For a successful file read operation, the fifth byte of a REPORT_MAGIC_EVENT_BYTES message indicates if another message follows or not. Using this byte as a flag, the host would know when the data transfer of a large file is complete.

 

The Magic Object

Going back to our working model for a file read operation, the host would need to send a WRITE_MAGIC_BYTES message to the display module (step 1). The display module then performs a file read operation (step 2) and sends back the contents of the file to the host in the form of REPORT_MAGIC_EVENT_BYTES messages, along with an ACK byte (step 3).

We have also seen that the demo “FileAccess.4DGenie” expects the host to follow a certain format for a WRITE_MAGIC_BYTES message. The demo “FileAccess.4DGenie” also follows a certain format when it constructs a REPORT_MAGIC_EVENT_BYTES message to be sent back to the host. These formats are in addition to the standard formats of WRITE_MAGIC_BYTES and REPORT_MAGIC_EVENT_BYTES messages described in the ViSi-Genie Reference Manual.

The demo “FileAccess.4DGenie” uses a Magic Object to receive and handle WRITE_MAGIC_BYTES messages, to perform the requested operation, and to send REPORT_MAGIC_EVENT_BYTES messages.

The prototype of the 4DGL function inside a Magic Object is:

rMagicObject0(var action, var object, var newVal, var *ptr);

Since this function will be used to receive and handle the WRITE_MAGIC_BYTES message coming from the host, it is expected that the passed parameters will give the user access to the received WRITE_MAGIC_BYTES message. Below are the descriptions of the parameters, as per the section “5.1 Genie Magic callable Functions” of the ViSi-Genie Reference Manual.

 

For the example project “FileAccess.4DGenie”, the parameter “action” is WRITE_MAGIC_BYTES. The parameter “object” is MagicObject0. The parameter “newVal” is the length of the array or the combined length of the command byte and the filename string. The parameter “ptr” is a pointer to the array which will contain the data from the host.

 

Diagram A. Implementation of the General Model Using a Magic Object

Attached is the PDF file “programFlow.pdf”. It contains three diagrams, the first of which illustrates the implementation of the general model. This diagram represents the example project “FileAccess.4DGenie”. The area bounded by the broken lines is implemented using a Magic Object.

 

Diagram B. Implementation of the File Access Model Using a Magic Object

The second diagram of the PDF file “programFlow.pdf” represents the scope of this application note – the file read operation.

 

Is the Message a WRITE_MAGIC_BYTES Message?

 

Parse the Array for the Filename

The array pointed to by ptr is an array composed of 16-bit elements. The filename is to be extracted from this array. In 4DGL, characters can be stored as 16-bit elements in an array (word-aligned) or as a string (byte-aligned). The string class functions apply only to strings. To illustrate:

 

Note the difference in endianness and manner of storage. The message received from the host is stored in the array pointed to by ptr. This array is internal to Genie and is word-aligned. Since the demo “FileAccess.4DGenie” uses string class functions to operate on the filename, there is therefore a need to convert the ordinary 16-bit element array containing the filename to a 4DGL string. Hence the routine

 

The 4DGL string class operations can now be used to operate on or manipulate the filename converted as a 4DGL string. Prior to this however, a string pointer to the filename must be defined.

 

For more information on 4DGL strings, please refer to the Picaso or Diablo16 Internal Functions Reference Manual. Right-click on a string class function name text and choose “Context Sensitive help” to open the manual. Also, the application note below discusses strings in 4DGL.

Designer or ViSi String Class Function

 

Start Constructing the REPORT_MAGIC_EVENT_BYTES Message

To know more about the function “seroutCS(…)”,see section 5.1 Genie Magic callable Functions of the ViSi-Genie Reference Manual.

 

Extract the Command Byte

 

Is cmd Equal to “MFILE_READ”?

 

 

Diagram C. File Read Operation

The third diagram of the PDF file “programFlow.pdf” presents a more detailed view of the file read operation.

 

Open the File

 

The function “file_Open(…)” is one of the several FAT16 file functions in 4DGL. FAT16 file functions are used mainly for accessing and modifying files on a FAT16-formatted uSD card. For more information on the FAT16 file functions, please refer to the Picaso or Diablo16 Internal Functions Reference Manual. Right-click on a FAT16 file function name text and choose “Context Sensitive help” to open the manual.

 

Check for Error

 

Get the File Size

 

The function “file_Size(…)” is one of the several FAT16 file functions in 4DGL. FAT16 file functions are used mainly for accessing and modifying files on a FAT16-formatted uSD card. For more information on the FAT16 file functions, please refer to the Picaso or Diablo16 Internal Functions Reference Manual. Right-click on a FAT16 file function name text and choose “Context Sensitive help” to open the manual.

 

Get a Byte from the File then Send it to the Serial Port

 

The function “file_GetC(…)” is one of the several FAT16 file functions in 4DGL. FAT16 file functions are used mainly for accessing and modifying files on a FAT16-formatted uSD card. For more information on the FAT16 file functions, please refer to the Picaso or Diablo16 Internal Functions Reference Manual. Right-click on a FAT16 file function name text and choose “Context Sensitive help” to open the manual.

 

Build and Upload the Project

For instructions on how to build and upload a ViSi-Genie project to the target display, please refer to the section “Build and Upload the Project” of the application note

ViSi Genie Getting Started – First Project for Picaso Displays (for Picaso)

or

ViSi Genie Getting Started – First Project for Diablo16 Displays (for Diablo16).

 

The uLCD-32PTU and/or the uLCD-35DT display modules are commonly used as examples, but the procedure is the same for other displays.

 

Copy the uSD Card Files

Attached to this application note is the folder “uSD card files” which contains two files as shown below. Copy these files to the uSD card before inserting it to the uSD card slot of the display module.

 

Identify the Messages

The display module is going to send and receive messages to and from an external host. This section explains to the user how to interpret these messages. An understanding of this section is necessary for users who intend to interface the display to a host. The ViSi Genie Reference Manual is recommended for advanced users.

 

Use the GTX Tool to Analyse the Messages

Using the GTX or Genie Test eXecutor tool is one option to get the messages sent by the display to the host. Here the PC will be the host. The GTX tool is a part of the Workshop 4 IDE. It allows the user to receive, observe, and send messages from and to the display module. It is an essential debugging tool.

 

Launch the GTX Tool

Under the Tools menu click on the GTX tool button.

 

The Genie Test eXecutor window appears.

 

In this section we will illustrate three cases for the file read operation:

  1. The file does not exist
  2. The file is less than 253 bytes in size
  3. The file is more than 253 bytes in size

 

The File does not Exist

WRITE_MAGIC_BYTES Message

Send the MFILE_READ command and the filename as a WRITE_MAGIC_BYTES message.

 

 

The format of this message is:

 

REPORT_MAGIC_EVENT_BYTES Message

Since the file does not exist, the display module replies with a null or empty REPORT_MAGIC_EVENT_BYTES message and an ACK byte.

 

The format of this message is:

 

The File is Less than 253 Bytes in Size

WRITE_MAGIC_BYTES Message

Send the MFILE_READ command and the filename as a WRITE_MAGIC_BYTES message.

 

 

REPORT_MAGIC_EVENT_BYTES Message

Since the file is less than 253 bytes in size, the display module replies with a single REPORT_MAGIC_EVENT_BYTES message that contains the data inside the file and an ACK byte.

 

The File is more than 253 Bytes in Size

WRITE_MAGIC_BYTES Message

Send the MFILE_READ command and the filename as a WRITE_MAGIC_BYTES message.

 

 

REPORT_MAGIC_EVENT_BYTES Message

Since the file is more than 253 bytes in size, the contents are divided into two packets which are then inserted into REPORT_MAGIC_EVENT_BYTES messages.

 

 

 

Share: