|Description||This Application Note explores the possibilities provided by ViSi-Genie to work with the Raspberry Pi. In the project developed in this document, a uLCD-32WPTU and a model B Raspberry Pi running on a Linux Raspbian operating system are used.|
|Supported Processor||PICASO, Diablo16|
This Application Note explores the possibilities provided by ViSi-Genie to work with the Raspberry Pi. In the project developed in this document, a uLCD-32WPTU and a Raspberry Pi model B running on a Raspbian operating system are used. This should also work with other versions of Raspberry Pi and 4D Systems displays.
Before getting started, the following are required:
- Any of the following 4D Picaso touch display modules:
2.4 inch resistive touch
2.8 inch resistive touch
3.2 inch resistive touch
and other superseded modules which support the ViSi Genie environment.
- The target module can also be a Diablo16 touch display
2.4 inch resistive touch
2.8 inch resistive touch
3.2 inch resistive or capacitive touch
3.5 inch resistive or capacitive touch
4.3 inch resistive or capacitive touch
5.0 inch resistive or capacitive touch
7.0 inch resistive or capacitive touch
Visit www.4dsystems.com.au/products to see the latest touch display module products that use the Diablo16 processor. The display module used in this application note is the uLCD-32WPTU, which is a Picaso display. This application note is applicable to Diablo16 display modules as well.
- 4D Programming Cable or µUSB-PA5
- micro-SD (µSD) memory card
- Workshop4 IDE (installed according to the installation document)
- A working Raspberry Pi (with Raspbian OS – this will need another µSD card)
- Ethernet (network) cable / Wi-Fi dongle – network connection is optional but recommended for easier installation of libraries
A 4D Raspberry Pi Adaptor or connecting wires
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). The user can simply click on the desired widget to select it and click on the simulated display to place the widget. The following are examples of widgets or objects used in this application note.
The purpose of this application note is to introduce the use of the basic ViSi-Genie-Raspberry-Pi library functions. The application consists of a 4D Picaso display module displaying four objects – a LED digits, a slider, a cool gauge, and a text string. These objects interact with the Raspberry Pi in a manner illustrated below.
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 four objects. The final form will look like as shown below, with the labels excluded.
The procedure for adding each of these objects will now be discussed.
The cool gauge constantly receives values from the Raspberry Pi. The dial of the cool gauge will constantly move to correspond with the received values. To add 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 put the cool gauge in place. 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 Raspberry Pi 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 the Raspberry Pi, 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 Raspberry Pi on the screen. To add a text string object, go to the Labels pane then click on the strings icon.
Click on the WYSIWYG screen to put the string in place. Again, the WYSIWYG screen simulates the actual appearance of the display module screen.
The area 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 Raspberry Pi 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 the 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 polled by the Raspberry Pi. A slider, for example, can be configured to report its current status to the Raspberry Pi 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 Raspberry Pi. 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 Raspberry Pi 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 Raspberry Pi. 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.
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 or the Raspberry Pi. 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 Raspberry Pi. 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 Raspberry Pi. Here the PC will be the host, instead of the Raspberry Pi. 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 tool menu 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 (the Raspberry Pi or the PC) 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 Raspberry Pi thru the ViSi-Genie-RaspPi-Library 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 Raspberry Pi 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 Raspberry Pi or the PC 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. The ViSi-Genie program developed in this application note simply waits for REPORT_EVENT messages. The process of polling the display and receiving REPORT_OBJ messages will be covered in a separate application note.
Experimentation with the different objects using the GTX tool is now left to the user as an exercise. The following tables are shown below as a 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 open the C source code demo in the Raspberry Pi and how to compile it and make it work with the display module. It is assumed that the user has the Raspbian OS installed on an SD card or a µSD card with an SD card adaptor for the Raspberry Pi and has a basic understanding of the C programming language. Inexperienced users may need to frequently refer to C programming tutorial sites for more information. For first-time Raspberry Pi users, the following pages are recommended:
During start up the terminal prompts for the log in details.
By default the username is “pi”.
The default password is “raspberry”. When typing the password, the characters are not displayed, so type carefully.
After a successful log in:
Type “startx” to proceed. Use a web browser (Midori for example) to download and install the ViSi-Genie-RaspPi library. The Raspberry Pi needs to be connected to the Internet for this.
If not connected to the Internet, it is also possible to put all the necessary files into a USB flash drive and copy them to the Raspberry Pi.
The ViSi-Genie-RaspPi-Library files are located here:
On the right side of the github page, click on the Download ZIP button.
Extract the library files to a folder.
Take note of the location of the files. Here the files are located inside the folder “ViSi-Genie-RaspPi-Library-master”.
On the desktop, double-click on the LXTerminal icon.
The terminal window appears.
Navigate to the folder where the library files are located by typing the command as shown below.
To compile the source code type make.
To install, type sudo make install.
The library is now installed.
Installation of the wiringPi library is optional but is needed to run some of the ViSi-Genie-Raspberry-Pi demo files in the 4D Systems github repository page. Installation of this library is also recommended since future application notes may require its use. Instructions for installing the library can be found on the same page where the ViSi-Genie-RaspPi-Library files are located: https://github.com/4dsystems/ViSi-Genie-RaspPi-Library. To know more about the wiringPi library and the detailed steps on how to install it, go to https://projects.drogon.net/raspberry-pi/wiringpi/.
The Raspberry Pi will use the serial port to talk to the display. However, by default it is used for a login shell. This needs to be disabled to be able to use the serial port properly.
Launch the tool from the terminal by using the command:
Raspberry Pi Software Configuration Tool opens.
Select Interfacing Options and press Enter
Another set of options will appear.
Select Serial and press Enter
You will be asked if you would like a login shell to be accessible over serial.
Select No and press Enter.
Then you will be asked if you would like the serial port hardware to be enabled.
Select Yes and press Enter.
Press Enter again to return to the first set of menus.
Select Finish and press Enter.
When prompted to reboot, select Yes and press Enter.
This document comes with a demo source code written in C and an accompanying make file. Save these files inside a folder in the Raspberry Pi (either transfer them using a USB flash drive or download them from the Internet if the Raspberry Pi has a network connection). In this tutorial, the files are saved in the location shown below.
Open the file basicDemo.c. Note that comments have been added to the code to help the user. Additional explanations are now given below. Discussion starts with the main function.
There are two tasks to be carried out by the program. One of these is that it waits for messages from the slider and then it writes the values contained in these messages back to the LED digits. The other task is that it constantly writes to the cool gauge. The first task is assigned to the main program. The second task is assigned to a thread. One can think of a thread as another program running in parallel with the main program. The virtual effect is that the program is writing to the cool gauge while simultaneously receiving messages from the slider and writing to the LED digits. The first statement inside the main function declares a thread.
About ten lines below the declaration, the thread is created and started.
The third argument, handleCoolGauge, is the routine that the thread will execute, once it is created. Note that this routine is at the beginning part of the source code.
Observe the correct syntax when creating a thread routine.
Of particular importance in thread routine is the function
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-RaspPi library. All of the objects can be written to except GENIE_OBJ_KEYBOARD and GENIE_OBJ_STATIC_TEXT.
Following the thread declaration is the statement
A structure, reply, of the genieReplyStruct type is now created. It contains four variables, each of which will hold a corresponding byte to be received from the display module. To illustrate:
The last variable, data, will hold the MSB and LSB data bytes of a message from the display.
The following lines will print some informative text on the Raspberry Pi’s terminal.
N.B.: Again, remember that the baud rate of the display module should match that of the Raspberry Pi.
To send a string to the display module, use the function
Note that two arguments are required – the first being the index of the strings object to be written to and the second being the text to be displayed.
The following block is the core part of the main program.
There are three tasks being performed in this block. First, it is checked if there are pending messages from the display.
A message represents a reply or an event from any of the objects in the display module. Messages are actually queued in the background, starting from the moment that the serial port is successfully opened. If there are pending messages, one is taken out from the queue and copied to the previously created genieReplyStruct structure, reply.
After having copied the contents of the actual message to reply, a user-defined function is now called to process the reply. This user-defined function is the event handler.
This function is responsible for evaluating the message received from the display.
The message is broken down into its components using nested IF statements. First, the cmd or command byte is checked if it is a GENIE_REPORT_EVENT.
Objects in ViSi-Genie can be set to report a message when their status has changed. This message will have the command byte GENIE_REPORT_EVENT. Here is a list of Genie commands taken from the .h file of the ViSi-Genie-RaspPi library.
Then the object byte is tested if it is that of a slider.
Lastly, the index byte is checked if it is equal to 0, which means that the message is from Slider0.
After having performed this series of confirmations, the program now writes the value contained by the data bytes of the message to Leddigits0.
Compile the demo source code first before running it. On the desktop, double-click on the LXTerminal icon.
The terminal window appears.
Navigate to the folder where the demo files are located by typing the command as shown below.
To compile the source code type make.
Notice that two additional files are created in the folder. One of these is an executable file.
Before running the program, connect the display module to the Raspberry Pi first. See the following section “Connect the 4D Display Module to the Raspberry Pi” then return here. To run the program, type the command shown below.
The program now runs.
The make file is used to compile the source code. After having written a new C source code, the user has the option of using the make file that comes with this application note. The make file needs to be edited though. This section shows how this is done.
First, save the new source code and a copy of the make file inside a folder. In this example, the source code, named sample.c, and the make file are saved inside the folder /genieBasic.
Next, open the make file and replace the text highlighted below with the filename of the new source code.
Save the file.
To compile the source code type make.
If there are no errors, the source code will now compile.
Notice that two additional files are created in the folder. One of these is the executable file.
To run the program, type the command shown below.
This section discusses how to connect the display module to the Raspberry Pi. The user has the option of using a 4D Serial Pi Adaptor or simply connecting the Tx0, Rx0, 5V, and GND pins of the display module to the corresponding pins of the Raspberry Pi.
When using the 4D Serial Pi Adaptor, the display module is powered from the Raspberry Pi’s 5V bus. The power supply therefore must be able to provide enough current to both the Raspberry Pi and the display module.
The complete setup:
Check the orientation of the 5-way-cable-to-adaptor connection.
Check the orientation of the 5-way-cable-to-display-module connection.