AN-00163 ViSi-Genie Magic How to Append to a File

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.
Supported Processor PICASO, DIABLO16
Supported Environment ViSi-Genie
Difficulty Medium

 

File Downloads
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_APPEND” is discussed. The implementation of a file append operation further requires the use of the following 4DGL features and functions in combination with the Magic 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.

This application note requires:

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. The display module used in this application note is the uLCD-32PTU, which is a Picaso display. This application note is applicable to Diablo16 display modules as well.

for non-gen4 displays(uLCD-xxx)

for gen4 displays (gen4-uLCD-xxx)

  • 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.

 

Application Overview

In the past it was not possible for a host to access files stored on 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 20 bytes from the host. The 20 bytes can contain an instruction byte (e.g. a file append), a null-terminated 8.3 format filename (e.g. "datalog1.txt"), and several bytes to be appended to the target file. Upon receiving these the display module will open the file (if it exists) and will append to it the received bytes. The ViSi-Genie example project “FileAccess.4DGenie” is an implementation 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 Append

Below is a model specific to an application that performs a file append 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_APPEND.

 

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:

 

The section “2.1.3.8 Write Magic Bytes” further says:

 

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

 

Where xxx is the value set in the Workshop options configuration interface.

 

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

 

To append to the file “new.txt” the bytes “0xAB”, “0xCD”, and “0xEF”, 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 write or append operation, as implemented in FileAcces.4DGenie, will have the following additional data.

 

Below is an example of a REPORT_MAGIC_EVENT_BYTES message for a successful file append operation.

 

File Open Error

If an error occurs during the file open-and-append operation, 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 append.

 

The Magic Object

Going back to our working model for a file append 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 append operation (step 2) and sends back a REPORT_MAGIC_EVENT_BYTES message, 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, the filename string, and the bytes to be appended to the target file. The parameter “ptr” is a pointer to the array which will contain the data from the host.

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

 

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 append 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 using the filename “ascii.txt”:

 

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 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_APPEND”?

 

Diagram C. File Append Operation

The third diagram of the PDF file “programFlow.pdf” presents a more detailed view of the file append 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 Filename String Length

 

The function “str_Length (…)” is one of the string class functions in 4DGL. These functions are used mainly for evaluating and manipulating strings. For more information on the string class 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.

Append the Received Data to the File

 

The function “file_Write(…)” 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.

 

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.

 

Append Hexadecimal Bytes to the Target File

WRITE_MAGIC_BYTES Message

Send the MFILE_APPEND command, the filename, and the data to be appended, as a WRITE_MAGIC_BYTES message.

 

The GTX tool sends the WRITE_MAGIC_BYTES message.

 

The format of this message is:

 

REPORT_MAGIC_EVENT_BYTES Message

The display module replies with a REPORT_MAGIC_EVENT_BYTES message indicating that the operation was successful. Note that, as per the internal functions reference manual, the target file would actually be created if it does not exist.

The format of this message is:

 

Acknowledgment Byte

 

Append a String to the Target File

It is also possible to append a string of ASCII characters.

WRITE_MAGIC_BYTES Message

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

 

The GTX tool sends the WRITE_MAGIC_BYTES message.

 

The format of this message is:

 

REPORT_MAGIC_EVENT_BYTES Message

The display module replies with a REPORT_MAGIC_EVENT_BYTES message indicating that the operation was successful.

 

The format of this message is:

 

Acknowledgment Byte

 

Share: