Skip to content

ViSi-Genie Magic: Arduino How to Read a File


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 Workshop4 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 an 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 can send back the contents of the file (if it exists) to the host. This code presents a working example of the above.

This codebase example has two parts - the ViSi-Genie Magic project and the Arduino sketch. The attached ViSi-Genie Magic project is a modified version of the example project "FileAccess" found in Workshop4 Pro go to File -> Samples -> ViSi-Genie Magic(PICASO/DIABLO). FileAccess contains a working example of a Magic Object that handles and responds to file access instructions from a host. The Magic Object example can be edited and customised by users.

The ViSi-Genie-Arduino library, on the other hand, has been updated to include a function for sending messages to a Magic Object. The library also has a function for responding to messages from a Magic Object.

Below are the videos of the expected output. Kindly set the video quality to 1080p (fullscreen view) for best viewing experience.


Worskhop 4 PRO is needed for this codebase example.

Example 1

Example 2

Example 3


This codebase example assumes the reader can program the 4D Systems display module using Workshop4 IDE ViSi-Genie environment. Beginners are advised to read the following aplication notes.


Below were the steps involved in creating this code example:

  1. Compile the attached ViSi-Genie Magic project and upload the program to a uLCD-32PTU or any 4D Systems displays with PICASO, DIABLO-16, PIXXI-28 and PIXXI-44 graphics processors. Copy the supporting files to a uSD card mounted to the PC. Properly unmount the uSD card from the PC and mount it to the target display.


    1. The difference between the attached ViSi-Genie Magic project and the FileAccess example in Workshop4 Pro is the inclusion of delays into the Magic Object code of the latter. For both of the original and the attached modified versions of FileAccess, the maximum number of bytes that can be sent at once by MagicObject0 is 255 bytes. Hence for files with a size larger than 255 bytes, the content is divided into messages, each of which is 255 bytes long. The last message may be shorter. A 255-byte long message consists of two header bytes and then the actual data payload. The original FileAccess example sends these messages in succession. The ViSi-Genie-Arduino library, however, may not be able to handle the relatively fast inflow of data coming from the display. As a workaround, delays were included into the code of MagicObject0 of the original FileAcess example, hence the attached modified version. A screenshot image of the inserted delays can be found inside the attached folder "images" (insertedDelayGenie.png). The downside of this workaround is the slower transfer of data. However, users are free to customise further the code for MagicObject0 to suit their application.

    2. There are additional files that need to be copied to the uSD card of the display module. These are "data.log" and "ascii.txt". These filenames are hard coded in the attached sketch. Open the attached folder "uSD card files" and copy the contents to the uSD card.

  2. Compile and upload the attached sketch to an Arduino Uno. The sketch uses a software serial port for the display.


    Starting at line 60 of the attached sketch, you will find the following byte array declarations and definitions:

    byte filename[] = {MFILE_READ, 'D', 'A', 'T', 'A','.', 'L', 'O', 'G', NULL}; // Example 1
    //byte filename[] = {MFILE_READ, 'D','U','M','M','Y','.','T','X','T', NULL}; // Example 2
    //byte filename[] = {MFILE_READ, 'A', 'S', 'C', 'I','I','.', 'T','X','T', NULL}; // Example 3

    Choose (comment/uncomment) a line one at a time before compiling and uploading the sketch to the target board. A screenshot image of the expected output for each of the examples above can be found in the folder "images".

    • "expectedOutput_Example_1.png" - expected output for Example 1 above
    • "expectedOutput_Example_2.png" - expected output for Example 2 above
    • "expectedOutput_Example_3.png" - expected output for Example 3 above
  3. Properly connect the Arduino Uno to your target display. See the application notes - ViSi-Genie: Connecting a 4D Display to an Arduino for this.

    If without an Arduino host, you can still run this code example by performing step 1. Then use the GTX tool to send and receive messages to and from the display module.


Project File