ViSi-Genie: Spectrum
Details
| Number | 4D-AN-00027 |
| Difficulty | Medium |
| Supported Processors | PICASO, DIABLO-16, PIXXI-28, PIXXI-44 |
| Supported Environments | ViSi-Genie |
Description
The simple project developed in this application note demonstrates the use of the spectrum object. The spectrum can be used to visually indicate multiple quantity levels. It can be used as a bar graph or as an audio equalizer display, among other possible applications. The spectrum object is designed to be controlled by an external host controller. A section of this application note discusses the format of the messages for controlling the spectrum using the GTX Tool in Workshop.
Prerequisites
- General: How to Update the PmmC for DIABLO-16
- General: Migrating from PICASO-SGC-GFX to PICASO
- General: How to Update the PmmC for PICASO
- General: Partitioning a micro-SD into FAT and RAW Components
Application Overview
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 objects or 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 used in this application note.
The simple project developed in this application note demonstrates the use of the spectrum object. The spectrum can be used to visually indicate multiple quantity levels. It can be used as a bar graph or as an audio equalizer display, among other possible applications. The spectrum object is designed to be controlled by an external host controller. A section of this application note discusses the format of the messages for controlling the spectrum using the GTX Tool in Workshop.
Setup Procedure
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 with PICASO Displays
ViSi-Genie: Getting Started with DIABLO-16 Displays
Create a New Project
For instructions on how to create a new ViSi-Genie project, please refer to the section “Create a New Project” of the application note.
ViSi-Genie: Getting Started with PICASO Displays
ViSi-Genie: Getting Started with DIABLO-16 Displays
Design the Project
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 trackbars, sliders, displays or keyboards. Below is an empty form.
At the end of this section, the user will able to create a form with three objects. The final form will look like as shown below, with the labels excluded.
When the program runs, the display module will look like as shown below.
The procedure for adding each of these objects will now be discussed.
Adding a Gradient Background
To add a gradient, go to the Backgrounds pane then click on the gradient icon.
Click on the WYSIWYG (What-You-See-Is-What-You-Get) screen to put the object 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 gradient background object named Gradient0.
Take time to experiment with the different properties. The gradient background used in this project has the following properties.
The updated appearance of the WYSIWYG screen is shown below.
Adding a Scale
To add a scale, go to the Backgrounds pane and click on the scale icon.
Click on the WYSIWYG screen to place the object.
The Object Inspector on the right part of the screen displays all the properties of the newly created scale named Scale0. The scale object used in this project has the following properties.
Shown below is the final appearance of the scale.
Selecting Objects
To inspect or edit the properties of an object, simply click on it in the WYSIWYG screen. When a background object occupying a large part of the screen is selected however, the foreground objects tend to disappear from the WYSIWYG. To illustrate:
To make a foreground object reappear, simply go to the object inspector of the currently selected object, and click on the drop-down arrow of the object line.
Observe that the drop-down menu lists three objects. Select an object (Scale0 for example) to make it reappear on the WYSIWYG screen. An alternative way is to create the background object last, so as to avoid inadvertently selecting it when clicking on the WYSIWYG screen. Another option is to make use of a background image instead.
Adding a Background Image
This section only illustrates how to add a background image in a new ViSi-Genie project. To add a background image, go to the object inspector, and click on the drop-down arrow of the Object line.
Select Form0 if there are other objects. Click on the
symbol of the Image property.
A standard open window asks for a file. Here a snapshot image file of the gradient background in the WYSIWYG screen will be used. The Image + Video Converter window appears. It shows the source and the output appearances of the image. Click on the OK button.
In the object inspector, click on the drop-down arrow of the Bgtype property and choose Image.
The WYSIWYG screen is now updated. When new objects are added, the image remains in the background.
Adding a Spectrum
To add a spectrum, go to the Gauges pane and select the Spectrum icon.
Click on the WYSIWYG screen to place the object.
The object inspector shows the properties of the spectrum. Take time to experiment with the different properties. The spectrum used in this project has the following properties. Individually set each of these properties and observe the results on the WYSIWYG.
The updated appearance of the spectrum is shown below.
Note
The spectrum has 24 columns, each of which can be arbitrarily made to display a certain value. Each column has three segments or areas.
The colours of a segment are determined by its palette properties.
The length of a segment is determined by its Percent property.
Naming of Objects
Naming is important to differentiate between objects of the same kind. For instance, suppose the user adds another spectrum object to the WYSIWYG screen. This object will be given the name Spectrum1 – it being the second spectrum object in the program. The third spectrum will be given the name Spectrum2, 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.
Build and Upload the Project
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.
ViSi-Genie: Getting Started with PICASO Displays
ViSi-Genie: Getting Started with DIABLO-16 Displays
The uLCD-32PTU and/or the uLCD-35DT display modules are commonly used as examples, but the procedure is the same for other displays.
Identify the Messages
The display module is going to receive and send messages from and to an external host. This section explains to the user how to interpret these messages. An understanding of this section is necessary for users who intend to interface the display to a host. The ViSi-Genie Reference Manual is recommended for advanced users.
Use the GTX Tool to Analyze the Messages
Using the GTX or Genie Test eXecutor tool is the first option to get the messages sent by the screen to the host. Here the PC will be 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.
Launch the GTX Tool
Under Tools menu click on the GTX tool button.
A new window appears, with the form and the spectrum object created previously.
The Spectrum
Control the Spectrum
Spectrum0 has 24 bars or columns, each of which can display a level between 0 and 100. To illustrate:
To change the level of the first bar (Bar 0) from 0 to 75, enter the integer 75 into the Pos box and press Set.
Note
On the display module, the first bar changes its level accordingly.
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:
| Command | Object Type | Object Index | Value MSB | Value LSB | Checksum |
|---|---|---|---|---|---|
| 01 | 18 | 00 | 00 | 4B | 52 |
| WRITE_OBJ | Spectrum | First | Bar 0 | Pos |
The message stands for “Write to the first spectrum object on the display module the value 0x004B.” Converting the hexadecimal value 0x004B to decimal will yield the value 0075. The MSB value identifies which bar or column lights up (here it is 00 = bar 0), and the LSB value determines the level to be displayed (here it is 75).
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 shall be handled by the host.
ACK = 0x06 as shown below
is an acknowledgment from the display module which means that it has understood the message.
Send a Hex File
Try sending messages to the different bars of the spectrum. Remember that the spectrum has 24 bars only and that each bar can display values between 0 and 100 only. When the display module is connected to a host controller, it is expected that a series of properly formatted messages will be received. To see the spectrum in action, click on the Send File button.
A standard open window asks for a hex file. Navigate to the documents folder of your Workshop IDE (for example: C:\Users\Public\Documents\4D Labs\PICASO ViSi-Genie). Select the file “spectrum.hex”.
A succession of messages is sent to the display module. Note that this file is for demo purposes only and can only work with a 24-bar spectrum (displaying values between 0 and 100).
Communication between a 4D display module programmed with a ViSi-Genie application and an external host controller must follow the ViSi-Genie Communications Protocol, which is defined in the ViSi-Genie Reference Manual.