|Description||This application note shows how to write a sketch for an Arduino program that sends WRITE_MAGIC_BYTES messages to and handles REPORT_MAGIC_EVENT_BYTES messages coming from the display module.
Using the above messages, the program performs a file read operation, a file append operation, and then another file read operation. This sequence was used to show that information was indeed appended to the target file. To understand the file read part of the operation, the reader is advised to refer to the application notes ViSi-Genie Magic How to Read a File and ViSi-Genie Magic How to Read a File Arduino. This application note will focus on the file append aspect of the operation.
|Supported Processor||PICASO, DIABLO16|
This application note shows how to write a sketch for an Arduino program that sends WRITE_MAGIC_BYTES messages to and handles REPORT_MAGIC_EVENT_BYTES messages coming from the display module.
Note: Workshop Pro is needed for this application.
Before getting started, the following are required:
- Any of the following 4D Picaso display modules:
and other superseded modules which support the ViSi Genie environment
- The target module can also be a Diablo16 display
Visit www.4dsystems.com.au/products to see the latest display module products that use the Diablo16 processor.
- 4D Programming Cable / µUSB-PA5/uUSBPA5-II
for non-gen4 displays (uLCD-xxx)
- 4D Programming Cable & gen4-IB / 4D-UPA / gen4-PA
for gen4 displays (gen4-uLCD-xxx)
- micro-SD (µSD) memory card
- Workshop 4 IDE (installed according to the installation document)
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.
To understand this application note more quickly, the reader is advised to read and understand first the following application notes.
The application notes ViSi-Genie Magic How to Append to a File and ViSi-Genie Magic How to Read a File show 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. The Magic Object is one of the objects under the Magic pane. It is actually a 4DGL code that allows the user to customise the behaviour of a Genie program. The Magic Object handles the WRITE_MAGIC_BYTES messages coming from the host. A WRITE_MAGIC_BYTES message may contain a file operation command byte and a filename. The Magic Object then uses 4DGL string class and FAT16 file functions to perform the requested file access operation. The Magic Object then sends REPORT_MAGIC_EVENT_BYTES messages back to the host. A REPORT_MAGIC_EVENT_BYTES message may contain data read from the file, list of filenames, file size information, etc., and/or acknowledgment.
The application note ViSi-Genie Magic How to Read a File Arduino presents and discusses a sketch for an Arduino program that sends a WRITE_MAGIC_BYTES message to and receives and handles REPORT_MAGIC_EVENT_BYTES messages coming from the display module. The WRITE_MAGIC_BYTES message contains the name of the file to be read and the REPORT_MAGIC_EVENT_BYTES messages contain the contents of the file.
In this application note, a sketch for an Arduino program that performs a file read operation, a file append operation, and then another file read operation is discussed. This sequence was used to show that information was indeed appended to the target file. To understand the file read part of the operation, the reader is advised to refer to the application notes ViSi-Genie Magic How to Read a File and ViSi-Genie Magic How to Read a File Arduino. This application note will focus on the file append aspect of the operation.
Similar to the file read operation, the file append operation is implemented using WRITE_MAGIC_BYTES and REPORT_MAGIC_EVENT_BYTES messages. First the Arduino host sends a WRITE_MAGIC_BYTES message to the display module. The WRITE_MAGIC_BYTES message will contain the name of the file to which data will be appended and the data to be appended to the target file. The display module then performs the requested operation and sends a REPORT_MAGIC_EVENT_BYTES message back to the Arduino host. The REPORT_MAGIC_EVENT_BYTES message will contain a byte that indicates whether the operation was successful or not. The Arduino host then receives and interprets the REPORT_MAGIC_EVENT_BYTES message.
At this point, it is assumed that the reader has an understanding of the project described in the application note ViSi-Genie Magic How to Append to a File. The remaining task now is to write the sketch for the Arduino program and upload the program to the Arduino host.
Note 1: The attached sketch was tested on an Arduino Uno. A software serial port was used for communicating with the display. The hardware serial port, Serial0, was used for communicating with the Serial Monitor of the Arduino IDE.
Note 2: The attached ViSi-Genie project is a slightly modified version of the example project “FileAccess.4DGenie” in Workshop. The difference between the attached ViSi-Genie Magic project and the “FileAccess.4DGenie” example in Workshop 4 is the inclusion of delays into the Magic Object code of the former. See the image files "GenieMagicObjectCodeInsertedDelay_1.png" and "GenieMagicObjectCodeInsertedDelay_2.png" inside the attached folder "images". Delays were inserted to the ViSi-Genie project code to give the Arduino host time to “catch-up”. Without the inserted delays, the Arduino host would hang up or miss several bytes since it is performing other processes besides the handling of bytes coming from the display module. Users are free to customise further the code for MagicObject0 to suit their application.
Note 3: The file "data.log" needs to be copied to the uSD card of the display module. This filename is hard coded into the attached sketch. Open the attached folder "uSD card file" and copy the content to the uSD card.
A thorough understanding of the application note ViSi-Genie Connecting a 4D Display to an Arduino Host is required before attempting to proceed further beyond this point. ViSi-Genie Connecting a 4D Display to an Arduino Host provides all the basic information that a user needs to be able to get started with ViSi-Genie and Arduino. The following is a list of the topics discussed in ViSi-Genie Connecting a 4D Display to an Arduino Host.
- How to download and install the ViSi-Genie-Arduino library
- How to open a serial port for communicating with the display and how to set the baud rate
- The genieAttachEventHandler() function – for Genie Magic, the equivalent of this is AttachMagicByteReader( )
- How to reset the host and the display
- How to set the screen contrast
- How to send a text string
- The main loop
- Receiving data from the display
- The use of a non-blocking delay in the main loop
- How to change the status of an object
- How to know the status of an object
- The user’s event handler – for Genie Magic, the equivalent of this is myGenieMagicHandler()
Discussion of any of these topics is avoided in other ViSi-Genie-Arduino application notes unless necessary. Users are encouraged to read ViSi-Genie Connecting a 4D Display to an Arduino Host first.
Open the Arduino sketch “FileAppendSS.ino” and the PDF file “programFlow.pdf” attached to this document. The PDF file shows the flow of the program.
This simply tells the ViSi-Genie Arduino library which function to call to process the magic events received from the display. The function to be called is a user-defined function.
Refer to the section “Connect the Display Module to the Arduino Host” of the application note “ViSi-Genie Connecting a 4D Display 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
- Changing the Serial port of the Genie Program
- Changing the Maximum String Length
Note 1: The attached Arduino sketch uses a software serial port to communicate with the display module and a hardware serial port to communicate with Serial Monitor running on the PC.