|Description||This Application Note explores the possibilities provided by the ViSi-Genie environment in Workshop to work with an Arduino host. In this example, the host is an AVR ATmega328 microcontroller-based 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 with at least one UART serial port.|
|Supported Processor||PICASO, DIABLO16|
This Application Note explores the possibilities provided by the ViSi-Genie environment in Workshop to work with an Arduino host. In this example, the host is an AVR ATmega328 microcontroller-based 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 with at least one UART serial port. See specifications of Aduino boards here. 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
- 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)
- 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.
It is often difficult to design a graphical display without being able to see the immediate results of the application code. ViSi-Genie is the perfect software tool that allows users to see the instant results of their desired graphical layout with this large selection of gauges and meters (called widgets) that can simply be dragged and dropped onto the simulated module display. The following are examples of widgets or objects used in this application note.
This application note shows how to create a ViSi Genie program and how to use the ViSi Genie library for the Arduino IDE. To achieve these objectives, a simple project is developed. This consists of a 4D Picaso module displaying six objects – a LED digits, a slider, a cool gauge, a string, a user LED, and a static text (label). Several of these objects interact with an Arduino host in a manner illustrated below.
To recreate the application described in this demo, the user first creates a ViSi Genie program in the 4D Workshop IDE and downloads it to a 4D display module. The user can also download and open the already-completed ViSi Genie program from this Github repository:
The Arduino host, on the other hand, is programmed using the Arduino IDE. The latest ViSi-Genie-Arduino library files are in also in the Github repository referred to above.
This application note was written to guide the user in setting up a working system in the shortest possible time and to cover the important aspects in the simplest possible manner. For topics that require further explanations, references are pointed out to the user for further study.
Note: The latest version of the ViSi-Genie-Arduino library (as of July 2014) is
The library version can be checked by opening the library file “genieArduino.h”.
Instructions for installing the library are in the section “Program the Arduino Host”. Users are encouraged to always update to the latest version.
The user can download the ViSi-Genie project example from:
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
For instructions on how to create a new ViSi-Genie project, please refer to the section “Create a New Project” of the application note
Everything is now ready to start designing the project. Workshop 4 displays an empty screen, called Form0. A form is like a page on the screen. The form can contain widgets or objects, like sliders, displays or keyboards. Below is an empty form.
At the end of this section, the user will able to create a form with six objects. The final form will look like as shown below, with the labels excluded.
The procedures for adding each of these objects will now be discussed.
The cool gauge constantly receives values from the Arduino host. The dial of the cool gauge will constantly move to correspond with the received values. To create a cool gauge, go to the Gauges pane then click on the cool gauge icon.
Click on the WYSIWYG (What-You-See-Is-What-You-Get) screen to place the cool gauge. The WYSIWYG screen simulates the actual appearance of the display module screen.
The object can be dragged to any desired location and resized to the desired dimensions. The Object Inspector on the right part of the screen displays all the properties of the newly created cool gauge object named Coolgauge0.
Feel free to experiment with the different properties. Take note of the maximum and minimum values. These determine the range of values that can be sent from the Arduino host to the cool gauge. To know more about gauges, refer to ViSi-Genie Gauges.
Naming is important to differentiate between objects of the same kind. For instance, suppose the user adds another cool gauge object to the WYSIWYG screen. This object will be given the name Coolgauge1 – it being the second cool gauge in the program. The third cool gauge will be given the name Coolgauge2, and so on. An object’s name therefore identifies its kind and its unique index number. It has an ID (or type) and an index.
It is important to take note of an object’s ID and index. When programming in the Arduino IDE, an object’s status can be polled or changed if its ID and index are known. The process of doing this will be shown later.
The display module can print text strings received from the Arduino host on the screen. To create a text string object, go to the Labels pane then click on the strings icon.
Click on the WYSIWYG screen to place the string. Again, the WYSIWYG screen simulates the actual appearance of the display module screen.
The space inside the red box will be the space occupied by the text string to be displayed. The object can be dragged to any desired location and resized to the desired dimensions. The Object Inspector on the right part of the screen displays all properties of the newly created strings object named Strings0.
To add background and foreground colours for the text string, edit the properties as shown below.
Choose the desired colour and click OK.
Do the same for the foreground colour.
When done, the form should look similar to that shown below.
The slider sends a message to the Arduino host when its status has changed. To add a slider, go to the Inputs pane and click on the slider icon.
Click on the WYSIWYG screen to place a slider object. Drag the object to any desired location.
In the Object Inspector, the minimum value is 0 and maximum is 100 by default.
An object can report its current status independently without being asked by the Arduino host. A slider, for example, can be configured to report its current status to the host each time it is moved. To do this, click on the Events tab in the object inspector and click on the symbol in the OnChanged line.
The On event selection window appears. Select Report Message and click OK.
The Events pane is now updated.
Now every time the slider is moved or its status has changed, it sends a message to the host controller. To be more exact, the slider will send a report message when the stylus or finger moving it is lifted off the screen. Selecting the OnChanging event, on the other hand, causes the slider to send messages while it is being moved (the moving finger or stylus is not lifted off yet). To learn more about the onChanged and OnChanging events, read the application note ViSi-Genie onChanging-and-onChanged-Events.
The message or data being sent has a format which the Arduino host must understand. A section of this application note is dedicated to explaining this format (called the ViSi-Genie Communication Protocol) used by the display module. Advanced users may refer to the ViSi-Genie User Reference Manual.
The LED digits object will display values received from the Arduino host. To add a LED digits object, go to the Digits pane and select the first icon.
Click on the WYSIWYG screen to place it.
Go to the Object inspector and set the following property values.
The updated appearance of the LED digits object is shown below.
To add a user LED object, go to the Digits pane and select the user LED icon.
Click on the WYSIWYG screen to place it.
The properties of Userled0 are:
The Static Text object is under the Backgrounds pane.
Click on the WYSIWYG screen to place it.
The property “Caption” defines the text to be displayed by Statictext0. The properties of Statictext0 are:
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
The uLCD-32PTU and/or the uLCD-35DT display modules are commonly used as examples, but the procedure is the same for other displays.
The display module is going to generate and send messages to the host. This section explains to the user how to interpret these messages. An understanding of this section is necessary for the user to be able to properly program the host controller. The ViSi-Genie User Reference Manual is recommended for advanced users.
Using the GTX or Genie Test eXecutor tool is the first option to get the messages sent by the screen to 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.
Under Tools click on the GTX tool button.
A new window appears, with the form and objects created previously.
In the GTX tool window, move the slider and press Set. On the display module, note that the slider has moved.
Also, messages are sent to and received from the display module.
The white area on the right displays
- in green the messages sent to the display module
- and in red the messages received from the display module
The actual message bytes are those inside the brackets. These values are in hexadecimal. The figure preceding the actual message is the computer time at which the message is sent. A label is also included to tell the observer what the message represents.
The message sent is formatted according to the following pattern:
The message stands for “Write to the first slider object on the display module the value 0x001F.” Converting the hexadecimal value 0x001F to decimal will yield the value 31.
The checksum is a means for the host to verify if the message received is correct. This byte is calculated by XOR’ing all bytes in the message from (and including) the CMD or command byte to the last parameter byte. Then, the result is appended to the end to yield the checksum byte. If the message is correct, XOR’ing all the bytes (including the checksum byte) will give a result of zero. Checking the integrity of a message using the checksum byte is handled automatically by the Arduino host thru the ViSi-Genie-Arduino library.
ACK = 0x06 as shown below
is an acknowledgment from the display module which means that it has understood the message.
Remember that the slider was configured to Report a Message when its status has changed. Now move the slider on the display module with a stylus or a finger. Observe the message sent by the display module to the PC.
The message from slider object is formatted according to the following pattern:
Suppose the slider object is not configured to report an event when it has moved. The host or the PC can ask the display module for the value of the slider by sending a message. Now on the display module move the slider randomly. In the GTX tool window press Query.
Observe the message area.
The PC sends a request message. The display module replies with the current value of the slider object. The messages sent and received are formatted according to the following patterns.
It is important to take note of the difference between REPORT_EVENT and REPORT_OBJ. REPORT_EVENT occurs if the user selects the event of a widget in Workshop to be "Report Message". There is no need for the host to ask the display module for the value of the slider. The slider independently sends its current status since it was configured to do so. Whereas REPORT_OBJ is a result of the user doing a read of an object from the host, using the Read Object function.
Experimentation with the different objects using the GTX tool is now left to the user as an exercise. The following tables are shown below for reference. Consult the ViSi-Genie User Reference Manual for more information.
This table is found in section 2.1 of the ViSi-Genie User Reference Manual .
This table is found in section 3.3 of the ViSi-Genie User Reference Manual.
This section discusses how to program the Arduino host to make it work with the display module. It is assumed that the user has a basic understanding of how the Arduino host works and how to program in the Arduino IDE. Inexperienced users may need to frequently refer to the Arduino website for more information.
The ViSi-Genie-Arduino library files are located here:
On the right side of the github page, click on the Download ZIP button. Save the zip file and extract its contents to the folder where additional Arduino libraries are saved.
Here is a link to a tutorial on installing additional libraries in the Arduino IDE.
In Windows for example, the library files will be saved here:
Remember to restart the Arduino IDE after installing the libraries. The genieArduino demo sketch should be accessible under the File – Examples menu.
Open the genieArduino_Demo sketch. Note that comments have been added to the code to help the user. Additional explanations are now given below.
In the setup (), the line shown below sets the data rate in bits per second (baud) for serial data transmission of the port Serial0.
The next line indicates that the ViSi-Genie-Arduino library will use the port Serial0 for communicating with the display.
Port Serial0 cannot be used therefore for any other purposes such as talking to the serial monitor. Logically, the 4D display should also communicate with the Arduino host at the same baud rate. To check the baud rate of the ViSi Genie program go to the project menu in Workshop.
To change the baud rate of the ViSi Genie program, simply click on the drop down arrow.
Choose the desired baud rate (9600 bps for instance) and download the program to the display module again. Now change the baud rate of the Arduino host as well.
For Arduino boards with four hardware serial ports (like the Due and Mega 2560), the user can choose another port to talk to the display. To use Serial2 at 9600 bps for example:
To use a software serial port,
Refer to the product page of your Arduino board to know the pins that can be used for a software serial port. The section “Connect the 4D Display Module to the Arduino Host” towards the end of this application note shows how the TX and RX pins of the host are connected to those of the display. The following are the SoftwareSerial baud rates that were tested to work with 4D displays using the basic application that comes with this application note..
As of writing, the latest version of the SoftwareSerial is documented to work at 115200 bps. This is easily demonstrated to be false as any interrupt (e.g. the timer interrupt that updates millis()) will result in software serial being unable to ‘extract’ the current byte being read. Thus the maximum, possibly reliable baud rate is 57600 bps. Therefore, since the library currently uses ‘calculated’ baud rates, other than the earlier fixed lookup table, users should be able to successfully test and use valid baud rates (lower than 57600 bps) other than those specified in the table above. Note that if other interrupts are in use the maximum baud rate may need to be lowered further. Users are encouraged to always use a hardware serial port of the Arduino host for talking to a 4D display. Refer to the Arduino website for more information on the issues and limitations of the SofwareSerial library.
N.B.: Again, remember that the baud rate of the display module should match that of the Arduino host. Also, when a serial port has been set to communicate with the display, it cannot be used for talking to other devices.
This function is used to tell the library the name of the function used in the user’s code space, so it knows what to call when an event is received and it needs processing. Full explanation is given in the section “Receiving Data from the Display”.
It is essential that the display is ‘ready’ before the host starts sending commands. To satisfy this condition, the host program can be made to reset the display and wait for some time (for the display to start up and initialize properly) before it starts sending commands. This sequence is ideally placed at the start of the host program. To illustrate:
If using the new 4D Arduino Adaptor Shield (Rev 2)
Note that the GPIO pin D4 of the Arduino host is used here for resetting the display. When using the new 4D Arduino Adaptor Shield (Rev 2.00 written on the PCB), simply connect RES to AR in jumper J1. See the section “Connect the 4D Display Module to the Arduino Host”. If using the old 4D Arduino Adaptor Shield (Rev 1), simply change the code above. Use pin 2 instead of pin 4.
If using the old 4D Arduino Adaptor Shield (Rev 1)
If using jumper connecting wires, connect the RESET pin of the display module to the D4 pin of the Arduino with a 1kohm series resistor in between (see the section “Connect the 4D Display Module to the Arduino Host”), and modify the code as shown below.
If using jumper wires
Note that the logic state for resetting the display is reversed if not using any of the 4D Arduino Adaptor Shields. It is now 0 instead of 1. This is because the display module’s RESET pin is directly connected to D4 via a 1kohm resistor. If using a 4D Arduino Adaptor Shield, the display module’s RESET pin is switched by the D4 pin via a transistor.
To make sure that the LCD is turned on, write
A contrast value of 1 can be too low for displays that support contrast levels from 0 to 15. Use a higher contrast level value for these displays. Read further below for more information.
To turn off the display, write
Most Picaso display modules can only have a value of 1 or 0 (on or off) for contrast. The uLCD-43P/PT/PCT modules and Diablo16 display modules, however, support contrast values from 0 to 15, which makes power saving possible. This function does not apply to uVGA-II/III modules. Check the datasheet of your display for more information.
To write to a string object on the display, write,
The first argument of the member function WriteStr() is the index of the string object to which the string will be sent. The second argument is a null-terminated character array. GENIE_VERSION is a string constant defined in the ViSi-Genie-Arduino library.
This is now the main part of the program. Three variables are declared and used here – waitPeriod for checking how much time has elapsed, gaugeAddVal holds the increment or decrement value of the cool gauge, and gaugeVal holds the value to be sent to the cool gauge.
The function below receives and queues the data received from the display.
Another function (to be written by the user) is needed to process the received data. The function genie.DoEvents() will call this user-defined function internally. A diagram of how data from the display is received and processed is now shown on the next page.
Note how the main loop uses a non-blocking delay to be able to execute other instructions besides genie.DoEvents(). Ideally, genie.DoEvents() is the main task and it should be called as often as possible such that all events from the display are processed immediately. The main loop can be represented with the flow chart in the right column. This flow chart is the recommended model for Arduino programs communicating with a 4D display. The use of the function delay() is discouraged since events from the display will not be processed in “real time”. Also, the time duration for the execution of other instructions/subroutines besides genie.DoEvents() should be kept as short as possible.
To sum it up, the display sends information to the Arduino, whether it is by result of a Reported Message or from a Read Object. The Arduino is executing its code in the main loop. It comes to the genie.DoEvents() function and calls the ViSi-Genie-Arduino library. The Arduino 'sees' there is some information available and stores it in a queue. When the Arduino processes the queue, the first event is taken out of the queue and processed based on the commands set out in the user-defined Event Handler function. The Arduino then returns to executing any other functions in its main loop, and then jumps to the start of the loop again.
To change the status of the cool gauge, use the function indicated below.
GENIE_OBJ_COOL_GAUGE is the object’s ID or type, 0x00 is the index, and gaugeVal is the value to be written to the object. Note that gaugeVal is incremented or decremented by gaugeAddVal. Also gaugeVal is limited to a value between and including 0 and 99. Remember that the cool gauge in the display module has minimum and maximum values of 0 and 100.
It is possible to change the status of any object as long as the object ID and index are known. The image below lists the object types or IDs already defined in the ViSi-Genie-Arduino library. All of the objects can be written to except the GENIE_OBJ_KEYBOARD and GENIE_OBJ_STATIC_TEXT.
This list is found in the library file “genieArduino.h”.
The latest library may include more objects. Thus, the user must always update to the latest version.
The Arduino can interrogate the display module for the status of a certain object. For instance, read the current status of the user LED using the command indicated below.
The status of any object can be read as long as the object ID and index are known. The display module will then reply with a message containing the object’s current status. This message is received and queued by genie.DoEvents() and dequeued and evaluated by the user’s event handler.
First, the union Event of the genieFrame type is declared.
The genieFrame union type is defined in the ViSi-Genie-Arduino library. It contains the structure reportObject, which is of the FrameReportObj type.
The FrameReportObj structure type contains five bytes, each representing a byte to be received from the display module. To illustrate:
The next step now is to take an event or a message from the event queue of the genie.DoEvents() function. Observe the correct syntax.
Then break down the message into its components. A part of the sketch demonstrates how this is done.
Here is a list of Genie command type constant definitions taken from the genieArduino.h file of the ViSi-Genie-Arduino library.
In conclusion the user’s event handler evaluates each byte of a message (command, object, object index, and value), and then makes a decision according to the result of this evaluation.
This section discusses several ways of connecting the display module to the Arduino host. The user has the option of using a 4D Arduino Adaptor Shield (there are two versions of this – the old and the new) or jumper wires.
The 5-way cable coming from the display should be connected to H1. When the Arduino host cannot supply enough power to the display, the display can be powered separately thru H2 (jumper J2 should be configured accordingly).
J1 is for choosing which pin resets the display – either the RES pin of H2 or pin D4 of the Arduino host. J2 is for choosing the power supply source for the display – either the Arduino host or the programming module connected to H2 (if the Arduino host power supply is inadequate). The middle pin of J3, RX, goes to the TX pin of the display and must be tapped to the correct RX pin of the Arduino host. The middle pin of J4, TX, goes to the RX pin of the display and must be tapped to the correct TX pin of the Arduino host.
The image on the right column shows the default settings for jumpers J1 to J4.
- Pin D4 of the Arduino host resets the display (J1 shorts pins RES and AR).
- The Arduino host powers the display (J2 shorts pins PWR and AR).
- The Arduino host talks to the display thru port Serial0.
Default Settings for J3 and J4
Jumpers J3 and J4 are configured, by default, to connect RX (TX0 of the display module) to D0 (RX0 of the Arduino) and TX (RX0 of the display module) to D1 (TX0 of the Arduino). Communication in this case is thru Serial0 of the Arduino host and COM0 of the display module.
The Arduino Host Powers the Display
The following are images wherein the display module is powered by the Arduino host. Note that the power supply must be able to provide enough current for both the display module and the Arduino host. Refer to your display module’s datasheet for the specified supply current.
Using the USB cable (the Arduino host powers the display):
Using the jack(the Arduino host powers the display):
To use the other hardware serial ports of the Mega or Due, remove the jumper connectors of J3 and J4 and connect the display TX0 and RX0 pins to the desired Arduino serial port TX and RX pins using jumper wires.
If the display requires a higher current to operate (the uLCD-70DT for instance), it is not advisable to power it off the 5V out of the Arduino host. To power the display separately from the Arduino board, set J2 as shown below. Power will then be supplied to the display thru H2.
H2 is for the 4D USB Programming Cable or µUSB-PA5 (power supply source), and H1 is for the display module. The following image shows how the Arduino host and the 4D display are connected when they are powered separately.
Complete setup (host and display are powered separately):
Note that the display module cannot be programmed thru the µUSB-PA5 in this setup since H2 transfers power only. Before programming the display module, disconnect it first from the Arduino Adaptor Shield. Likewise, before programming the Arduino host, make sure that it is not connected to the display module. Do this when the communication is thru Serial0 (Arduino host) and COM0 (4D display). Always double check the orientation of the connections.
The old 4D Arduino Adaptor Shield (Rev1) uses digital pin D2 for resetting the display. The reset routine of the Arduino sketch must be modified accordingly.
Note that the display here is powered off the 5V out of the Arduino board. Pin D4 of the host will also reset the display (logic of the reset routine must be inverted). Connect the 5V and GND pins of the display to an external 5V power supply source if a separate supply is needed. The reset pin, RES, of the display can also be connected to another GPIO pin of the Arduino host and the sketch can be modified accordingly.
A ViSi-Genie program uses the serial port COM0 by default. This is also the serial port through which the display is programmed by Workshop. The datasheet for the uLCD-32PTU, for example, shows the H1 I/0 Expansion header and the programming header.
As the reader may have already perceived, the TX and RX pins on the programming header are the same pins as TX0 and RX0 on the H1 I/O expansion header. In Workshop it is possible to change the serial port being used by a ViSi-Genie program. Instructions for doing this are as follows.
Under the File menu, select Options then select the Genie tab.
For Picaso displays there are only two available serial ports – COM0 and COM1. To use COM1, click on the button next to it then click OK.
Compile and download the program to the display. All subsequent ViSi-Genie programs will now use COM1. Also, the TX and RX pins of the host shall now be connected to the RX and TX pins of COM1 instead of COM0.
The Diablo16 processor has four serial ports – COM0, COM1, COM2, and COM3. The TX and RX pins of COM0 are fixed and are used for programming the processor. Again, COM0 is also the default serial port used by a ViSi-Genie program. The TX and RX pins for COM1, COM2, and COM3, on the other hand, are ‘mappable’ – that is, they can be configured to be ‘mapped’ out to any (but not all) of the GPIO pins. The table below shows the GPIO pins that can be used as TX and RX pins for COM1, COM2, and COM3. This table is taken from the Diablo16 datasheet.
Workshop, however, only provides the option of using COM1 as an alternative to COM0. To use the GPIO pins PA13 and PA12 as RX and TX pins respectively, specify them under Diablo com1 Pins then click OK.
Compile and download the program to the display. All subsequent ViSi-Genie programs with a Diablo16 target display will now use COM1 with the specified TX and RX pins. Also, the TX and RX pins of the host shall now be connected to the specified RX and TX pins of COM1. If using a uLCD-35DT for example,
Consult the datasheet of your display for more information.
The host can dynamically write to the strings object of a ViSi-Genie program. The default maximum length of a character array that can be dynamically written to a strings object is 75 characters (excluding the overhead bytes). Worskhop provides an option for increasing this limit.
Under the File menu, select Options then select the Genie tab. Here the maximum length is set to 200 characters. Click OK.
Compile and download the program to the display. All subsequent ViSi-Genie programs will now have this configuration.