|Description||This application note demonstrates how to write to different objects using an Arduino host. This document is intended as a supplement to ViSi-Genie Connecting a 4D Display to an Arduino Host.|
|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:
- The target module can also be a Diablo16 display
See the section “Write to a Pin Output Object” when compiling this project for a Diablo16 display module.
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 gen-4 displays (gen4-uLCD-xxx)
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 some examples of widgets or objects used in this application note.
This document is a supplement to ViSi-Genie Connecting a 4D Display to an Arduino Host. The application of the Genie class member function WriteObject() function to different Genie objects is shown here. A ViSi-Genie program and an Arduino sketch are provided for demonstration purposes.
The ViSi Genie program contains the different objects created in Workshop. The Arduino sketch contains the commands to control each of these objects. To learn how to create a ViSi Genie program, go to http://www.4dsystems.com.au/blog/. The page contains application notes which explain how to create and configure objects in a ViSi-Genie program.
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 Diablo16 Displays (for Diablo16).
When creating objects in the Workshop IDE, objects are automatically named as they are created. For instance, the first cool gauge object added will be given the name Coolgauge0. The object name, along with the object properties, is shown by the Object Inspector.
Naming is important to differentiate between objects of the same kind. For example, suppose the user adds another cool gauge object to the WYSIWYG (What-You-See-Is-What-You-Get) 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, as will be shown in the next section.
The status of a ViSi-Genie object can be controlled or changed by a host controller with the appropriate message sent thru the serial port. The format of this message is defined in the ViSi Genie Communications Protocol which is discussed in the ViSi Genie User Reference Manual. To write to a ViSi-Genie object, the format is:
The ViSi-Genie-Arduino library implements this format as a function, the prototype for which is declared under the Genie class.
The first parameter must be an integer which specifies the object ID. The second parameter is an integer which specifies the index of the object. The third parameter is an integer which holds the data to be written to the object. Example:
Note that the third parameter must be an integer. Floats and other data types cannot be passed as an argument to this function. The Arduino platform provides functions for converting floats to integers. The user can refer to the Arduino website for further information.
String objects can display predefined text (created in the ViSi-Genie environment) or dynamic text received from the host. The process of making a string object display predefined text is discussed in the section “Write to a Predefined Strings Object”. For the host to write a dynamically created text to a string object, the format of the message is:
The function prototype for this in the ViSi-Genie-Arduino library is:
The first parameter is the index of the string. The second parameter is a pointer to a null-terminated character array. Examples:
Note that for all three examples, the second argument for genie.WriteStr() is a pointer to a null-terminated character array. Section 188.8.131.52 Write String (ASCII) Message of the ViSi-Genie Reference Manual emphasizes this.
It is a common mistake for beginners to use integers, strings, floats, and other data types instead of a pointer to a null-terminated character array as the second argument passed to genie.WriteStr() . The Arduino
platform provides functions for converting integers, strings, and floats to null-terminated character arrays. The user can refer to the Arduino website for further information.
The ViSi-Genie Arduino library handles the actual communication between the Arduino host and the display module, making sure that the message sent is of the correct format. This also includes error checksum coding, acknowledgment, etc. The user will just have to specify the strings object index and the string to be displayed when using genie.WriteStr().
The user can easily associate the syntax of the functions to the corresponding format in the ViSi-Genie Communications Protocol. Table 3.3 of the manual shows the objects and their ID numbers.
In the ViSi-Genie-Arduino library, the ID numbers are then used to define the Genie object constants.
The following sections now show how the genie.WriteObject() function is applied to different Genie objects. Writing to the keyboard, static text, image, and pin input objects is not possible.
To write to a DIP switch:
A three-second delay is added for the observer to see the object at the current state. Note that the function has three arguments as defined in the ViSi-Genie-Arduino library. The first argument is the Genie object to be written to, the second is the object index, and the third is the value which represents the state of the DIP switch. Thus, the command
yields the result
yields the result
Table 2.1.2 shows the format for writing to objects.
For further information, refer to the ViSi Genie User Reference Manual. The document gives an informative description of all of the Genie objects in relation to the ViSi Genie communications protocol.
The code above will make Knob0 change its state from 0 to 99, hence making it appear to rotate.
Similar to the DIP switch example, the code above displays the rocker switch at state 0 and then at state 1.
The code above will make Rotaryswitch0 change its state from 0 to 8. To learn how to configure a rotary switch, refer to ViSi-Genie Inputs.
Similar to the knob example, the code above will make Slider0 change its state from 0 to 99.
The code above will make Trackbar0 change its state from 0 to 99.
Similar to the DIP switch example, the code will show Winbutton0 at state 0 and then at state 1.
The button used in this example is configured as a toggle button. ViSi-Genie Advanced Buttons explains how to create a toggle button.
The second parameter, 0x01 is the index of the form to be activated. The third argument can be of any value since the Genie communications protocol does not require a value (MSB and LSB). See section 184.108.40.206 of the ViSi Genie User Reference Manual.
The code above will make Angularmeter0 change its state from 0 to 99.
The code above will make Coolgauge0 change its state from 0 to 99.
The code above will make Customdigits0 change its state from 0 to 99. To learn how to create a custom digits object, open the ViSi sample program in Workshop under File menu – Samples – Picaso ViSi – CLOCK. The block comment discusses how the bitmap image of the digits was created.
The code above will make Gauge0 change its state from 0 to 99.
Similar to the DIP switch example, the code above displays the LED at state 0 and then at state 1.
The code above will make Leddigits0 change its state from 0 to 99.
The code above will make Thermometer0 change its state from 50 to 149. Note that the value sent by the Arduino host is offset by 50. The user has to account for this offset.
The code above will make Meter0 change its state from 0 to 99.
The code above displays the Userled0 at state 0 and then at state 1.
The code above will play Video0. Take note of the frame values and delay. The Object Inspector shows the frame properties of a video.
The FrameDelay (milliseconds) is equal to the reciprocal of the frame rate (fps).
Besides displaying a dynamically created ASCII text received from the Arduino host, the user also has the option of displaying a predefined strings object created in the Workshop IDE. The document ViSi-Genie Labels, Text, and Strings discusses how predefined strings objects are created. Using predefined values makes the most efficient use of the communication link and also minimizes the code required in the host controller. In the ViSi Genie sample program, Strings6 contains four pages of text. Each of this page can be displayed by using the genie.WriteObject() function.
Note that genie.WriteStr( ) is for displaying a dynamically created string (from the host), while genie.WriteObject( ) is for displaying a predefined string (stored in the uSD card).
A timer object created in the Workshop IDE can be started or stopped by the host controller using the appropriate commands. Form0 of the ViSi Genie program has a timer object, Timer0, linked to Video1. When Timer0 starts, Video1 plays. Note that timer and sound objects always reside in Form0.
The sounds object is a special object such that there can only be one instance of it in a Genie program. Similar to the timer object, the sounds object is invisible and always resides in Form0. The document ViSi-Genie Play Sound explains how to create and control a sounds object. Section 220.127.116.11 of the ViSi Genie User Reference Manual explains how to control a sounds object when using a host controller. The code below shows how this is done when programming an Arduino host. The ViSi Genie program for this code has a Sounds object containing three tracks.
The user is encouraged to open the accompanying Arduino sketch file and read the comments.
The spectrum object is described with more detail in ViSi-Genie Spectrum.
The scope object is described in ViSi-Genie Single Trace Scope.
The tank object is documented in ViSi-Genie Tank.
The user images object is documented in ViSi-Genie User Images.
The pin output object is described in ViSi-Genie Pin Input and Output.
Note that the pin labels of a Picaso display module are different from those of a Diablo16 display. Since the ViSi-Genie project attached to this application note was designed using a Picaso display, it has to be modified if recompiled for a Diablo16 display. Reconfigure the pin assignment of a pin output object by using the object inspector. For a uLCD-35DT target display for example, refer to the following images.
BUS_0 is a pin label for Picaso displays. Change the pin assignment of PinOutput0 by choosing a new pin label from the new list provided for Diablo16 displays. Do the same for PinOutput1. Failure to perform these steps will result to a compilation error. Refer to the datasheet of your display for more information.
The 4D button object is described in ViSi-Genie 4D Buttons.
The animated button object is described in ViSi-Genie Animated Button.
In the following example, the LED is red when on or high; and green when off or low:
The colour picker object is described in ViSi-Genie Color Picker.
The colour picker object is described in ViSi-Genie User Button.