|Description||This application note shows how to create a new project, how to select the target display module, how to connect a display module to the PC, and how to compile and download a simple “Hello-world” program to the target device. This application note also introduces the 4DGL (4D Graphics Language) and the basic use of the WYSIWYG (What-You-See-Is-What-You-Get) screen.|
|Supported Processor||PICASO, DIABLO16|
This application note shows how to program a 4D display module in the ViSi environment to make it print text and display an object on the screen. 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. 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 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 is the perfect environment that allows users to see the instant results of their desired graphical layout. There is a selection of inbuilt dials, gauges, and meters (called widgets or objects) that can simply be dragged and dropped onto the simulated module display. From here, each object can have its properties edited and at the click of a button, all relevant code is produced in the user program.
This application note shows how to create a new project, how to select the target display module, how to connect a display module to the PC, and how to compile and download a simple “Hello-world” program to the target device. This application note also introduces the 4DGL (4D Graphics Language) and the basic use of the WYSIWYG (What-You-See-Is-What-You-Get) screen.
This application note uses a uLCD-32DT display module, which is, as of writing, a discontinued product, as the example target device. The procedures described, however, are applicable to Picaso and other Diablo16 displays.
This document comes with a demo ViSi project in a zip file.
In the file explorer window, extract the contents of the zip file to a desired location. The contents are a ViSi file and a Designer file.
The user can open the project by double-clicking on any of the two files or by selecting them in Workshop 4. Users who want to learn how to create a new ViSi project may proceed to the next section.
There is a shortcut for Workshop 4 on the desktop.
Launch Workshop 4 by double-clicking on the icon. Workshop 4 opens and displays the Recent page.
To load the existing project, click on Open.
A standard open window asks for a ViSi project. Select the demo file.
The project opens.
The attached project has its target display configured to be a uLCD-32DT. To change the target device, go to the Project menu and click on the display button
The Change Display window appears. Change the target display by clicking on the display name.
A drop-down menu will appear. Select your new target device.
Click OK to confirm when done.
Changing the orientation is done by manually editing the code. This will be discussed later.
There is a shortcut for Workshop 4 on the desktop. Launch Workshop 4 by double-clicking on the icon.
Workshop 4 opens and displays the Recent page.
To create a new project, there are two options.
Click on the top left-most icon, New.
Or Click on the icon beside Create a new Project.
The Choose-Your-Product window appears. Select the appropriate screen and preferred orientation. The screen used in this example is a uLCD-32DT (portrait orientation).
Select the desired orientation by clicking on the display on the right part of the Choose-Your-Product window.
The image of the display rotates as you click it. When done, click on the next button on the lower right part of the Choose-Your-Product window.
Everything is now ready to start designing the project. Workshop 4 displays the code area (left side – orange box) and the WYSIWYG screen (right side – red box).
Workshop 4 automatically provides a default code – a program skeleton to which developers can simply add their codes. The program skeleton contains the basic parts needed to start designing an application.
The first line of the default code defines the target device.
To include a source file in 4DGL, use the pre-processor directive “#inherit”. The program skeleton has three include files.
The user can view the contents of an include file by following the instructions below.
- Put the cursor on the filename.
- Click the right mouse button and a menu will appear. Select the first option (Open file at Cursor).
- Workshop 4 now opens the file 4DGL_16bitColours.fnc.
The file contains constants and their values. Values of constants do not change throughout the duration of the program.
The file 4DGL_16bitColours.fnc contains hexadecimal values of 140 commonly used colour constants. Scroll down to see all the defined colour constants. Take note of lines 8 and 149 below. This is how a block of constants is declared in 4DGL.
The include file "VisualConst.inc" contains constants for line patterns. Here each of the constants is defined as a single-line entry.
The include file "NoName6Const.inc" does not exist prior to the compilation of the project. The final name of this include file will be that of the project when it is saved. This include file will contain, among others, constant values of memory locations.
Lines 11 to 36 make up the main function of the program.
Note that the main function block starts with
and ends with
This is how a function is defined in 4DGL.
Single-line comments in 4DGL look like as shown below.
A block comment starts with “/*” and ends with “*/”, as shown below.
This application will need a µSD card. Before the uSD card can be accessed, it has to be initialized first. Observe that in the main function, an entire block is commented out. This block (lines 15 to 31) is a uSD-card-initialization routine and it defines the behaviour of the program while waiting for a µSD card to be inserted. Basically the routine flashes the string “Mounting…” while no uSD card is detected and successfully initialized. Remove the block comment symbols indicated below.
The code screen will be updated accordingly, showing the block as an actual part of the code.
will print the string “Mounting…” on the screen followed by a new line.
Lines 18 to 23 make up a while loop.
Note that the while loop starts with
and ends with
A loop in a program performs instructions repetitively. The while loop has the basic syntax
The statements or instructions inside the block are executed as long as the condition is true.
starts up the FAT16 disk file services. This function must be called before any other FAT16 file related functions can be used. The function returns a non-zero value if a memory card is present and successfully initialized, and a value of ‘0’ otherwise.
delays the execution of the program for 200 milliseconds.
To clear the screen, use the function
The repeat-forever loop is another kind of loop. It starts with
and ends with
The program will execute the statements between lines 34 and 35 indefinitely. Here the program actually does nothing indefinitely after printing the text “Hello World” since no instructions exist between lines 34 and 35. If this empty loop is omitted, the program exits the main function.
In this application note the user will learn how to add a static text widget or object to the WYSIWYG screen. Besides static texts, images, videos, buttons, and many others can also be added as objects to the WYSIWYG screen. When the user clicks on the Compile or Comp’nLoad button, Workshop combines all of these objects into a single graphics file, which is of a format readable by 4D graphics processors. There are actually two files generated – the GCI file and the DAT file. The GCI file contains the actual object images and the DAT file contains a list of the objects in the GCI file. Workshop copies these two files to a FAT16-formatted uSD card mounted on the PC. When the uSD card is unmounted from the PC and mounted to the display module and if the program is downloaded to the display module’s processor, the project will now run.
Note that the program is different from the graphics files. The program contains the instructions to be executed by the processor. It resides on and runs from the processor of the display module. The graphics files, on the other hand, are supporting files on the uSD card. These are accessed by the program during runtime. For more information on this important differentiation, refer to the application note ViSi-Genie Program Destination.
With the uSD card properly mounted by the uSD card initialization routine, the program can now access the GCI and DAT files using the function
This function returns a handle (a pointer to the memory allocation) to the image control list that has been created. In other words, we can use the variable “hndl” if we want to access the contents of the graphics files, e.g. if we want to display a certain object. To learn more about the file_LoadImageControl(…) function, consult the Picaso Internal Functions Reference Manual or the Diablo16 internal Functions Reference Manual.
Note: Workshop will automatically derive the filenames of the GCI and DAT files from the project name. The filenames will be reflected in the code and in the names of the actual GCI and DAT files. When the project is saved with the name “ViSiFirstProject”, line 30 of the code will be updated as shown below.
These will also be the names of the actual files generated inside the project folder and those copied to the uSD card. Note that the filenames follow the 8.3 format.
It is always a good practice to check if the filenames hardcoded into the code correspond to the actual names of the files on the uSD card. Although Workshop automatically does this in the background for you, other factors such as the settings of your PC may sometimes prevent Workshop from “synchronizing” the filenames.
To print “Hello World” on the screen, write
The function print() is another function for printing a string.
Go to the Widgets menu, select the Labels pane, and click on the static text icon.
Once the static text icon is selected, click on the WYSIWYG screen to place it.
The Object Inspector shows the different properties of the object. The object has the name “Statictext1”, which means that it is the first static text object added to the project. By default, an object has the same name and caption. Change the value of the property “Caption” from “Statictext1” to “Hello World”.
The WYSIWYG screen is updated accordingly.
In the code area, place the cursor somewhere between the “print("Hello World!");” statement and the repeat-forever loop.
With Statictext1 still selected, click on the “Paste Code” button of the Object Inspector.
A new line is added to the code. This is the command for showing the object Statictext1 on the screen.
After executing the uSD-card-initialization routine, the program will now print the string “Hello World” and will display the object Statictext1.
Save the program with the desired file name first.
Insert the µSD card into the USB adaptor and plug the USB adaptor into a USB port of the PC.
OR insert the µSD card into a µSD-to-SD card converter and plug the SD card converter into the SD card slot of the PC.
Check if the µSD card is mounted. In the image below, it is mounted as drive H:
Connect the display module to the PC using a 4D Programming Cable or a uUSB-PA5 adapter. Go to the Comms menu to check if the module is detected. The button should be blue in colour. Below is an example of how the Comms tab will look like if a uLCD-32DT is connected to the PC. Note that Workshop detects that the PmmC and driver of the connected display module are outdated.
Below is an example of how the Comms tab will look like if a uLCD-32PTU is connected to the PC.
If not familiar with how to actually connect a 4D display to the PC using a 4D USB programming cable or a uUSB-PA5 and with how to update the firmware, the user should consult the application notes below.
Under the Project menu, choose Flash as the destination.
To know more about the destination options “RAM” and “Flash”, read the application note General Downloading an Application Program to RAM or Flash Memory.
After making sure that the device is detected, go to the Home menu and click on the Comp n’Load (Compile and Download) button.
Workshop now builds the graphics files and copies them to the uSD card. The Copy Confirmation window appears. The user will be prompted to choose the correct drive for the memory card. Now choose the correct drive by clicking on the drop down arrow. Then click OK.
Workshop copies the supporting graphics files to the μSD card.
Workshop then downloads the program to the display module’s processor.
The message box will look like as shown below after a successful download.
The program should now run on the processor of the display module and it should be waiting for a uSD card.
In the section “Accessing the uSD Card”, it was emphasized that Workshop automatically derives the filenames of the GCI and DAT files from the project name. The filenames follow the 8.3 format and are used in the code and as the names of the actual GCI and DAT files. Before unmounting the uSD card from the PC, ensure that the files are present and that the filenames are correct.
Again, it is always a good practice to check if the filenames hardcoded into the code correspond to the actual names of the files on the uSD card. Although Workshop automatically does this in the background for you, other factors such as the settings of your PC may sometimes prevent Workshop from “synchronizing” the filenames. There are other supporting files besides the graphics files. Checking the names of these files both in the code and with the actual files may sometimes be necessary for troubleshooting purposes. For more information on the different types of supporting files, refer to the application note ViSi-Genie Program Destination.
Properly remove the μSD card from the PC and insert it into the μSD card slot of the display module.
The program prints the string “Hello World!” and displays the object Statictext1.
Item A is a string printed as a result of the instruction,
The string “Hello World” in this case is a literal constant inside the program.
Item B is an image retrieved from the uSD card and is displayed as a result of the instructions
You may consult the internal functions reference manual of your display module’s processor for more information. The manual can be opened from Workshop. To do so, put the cursor on the desired function name, click on the right mouse button, then choose “Context Sensitive help”.
Alternatively, you can also open the manual by pressing F1 while the cursor is on the function name.
One important thing to remember is that Workshop generates or builds the graphics for all the objects in the project during design time, when you click the Compile or Comp’nLoad button.
As previously discussed, all graphics are integrated into the supporting files, which are eventually copied to the uSD card. Thus, if you want to remove, change, or add an object from/in/to the project, you will have to update the contents of the uSD card. This means that you will have to unmount the uSD card from the display module and mount it back to the PC, so that Workshop can copy the newly generated files.
Workshop detects changes made with the objects of the project by monitoring the WYSIWYG area and the Object Inspector. For example, if you changed the label of a static text object or dragged a button object to a new location, Workshop will, after you click on the Compile, Compn’Load, or Download button, automatically generate a new set of supporting graphics files to be copied to the uSD card. As previously mentioned, again you will have to unmount the uSD card from the display module to update its contents.
However, if you haven’t touched the WYSIWYG area or modified any field in the Object Inspector, Workshop will not generate a new set of support files since it is not necessary. This behaviour is important because you wouldn’t want Workshop to be generating support files all the time, most especially when the project is large (Workshop may take a while to generate the graphics files of a very large project).
Changes made with the 4DGL code only will cause Workshop, after you click on the Compile button, to compile the program. You will then have to click on the Download button to make Workshop download the program to the processor. Alternatively, you can click on the Comp’nLoad button to make Workshop compile the code and download the program to the processor of the display module. Also, you will notice that Workshop displays the Compn’Load button or the Download button, depending on whether it has detected changes made with the code and/or objects, or not.
In summary, remember that, if you have made changes with the 4DGL code only, Worskhop will display the Compile button and the Compn’Load button. Clicking on the Compile button will cause Workshop to compile the code. To make Workshop compile the code and download the program to the processor of the display module, click on the Compn’Load button.
If no changes have been made with the code and/or objects recently, Workshop will display the Compile button and the Download button. Clicking on the Compile button will cause Workshop to compile the code. Clicking on the Download button will cause Workshop to download the program to the display module processor.
If Worskhop has detected changes made with the objects, it will always generate a new set of supporting files and will prompt you for the correct uSD card drive to which the supporting files will be copied.
It is not possible to change the properties of an object during runtime. For instance, changing the caption of a static text object or a button is not
possible when the program is running. Again, the graphics for the objects are generated or pre-rendered during design time.
Since supporting files can become significantly very large in size, Workshop always copies them directly to the uSD card, i.e. the uSD card has to be mounted to the PC. Programs, on the other hand, are relatively small in size. Hence, they can be downloaded to the display module processor through the programming cable. Note that the transfer rate when using the programming cable is very limited (in the range of several KB per second) compared to that when the uSD card is mounted to the PC (several MB per second).
Although impractical for large supporting files, there is a way to transfer small supporting files to the uSD card mounted on the display module through the programming cable. For more information, refer to the application note General Serial File Transfer from PC to Display Module uSD Card.