|Description||This application note primarily shows how to add a counter in the main loop and print it using Magic Objects.. The Magic Code and Event is under the Genie Magic pane in Workshop 4 Pro. In this application it contains a 4DGL code that adds a counter in the main loop and then prints if a button is pressed.cts.|
|Supported Processor||PICASO, DIABLO16|
This application note primarily shows how the Magic Event object is used to implement a project that features up and down button counters. The implementation of up and down button counters further requires the use of the following features and functions in combination with the Magic Event object:
- Timers and timer events
SendReport(…) and WriteObject(…) are examples of callable functions in the new ViSi-Genie Communications protocol. SendReport(…) causes the program to send a REPORT_EVENT or a REPORT_OBJ message to the serial port. This function can be inserted into the code of Genie Magic objects.
WriteObject(…) updates the values of Genie objects. This function can also be inserted into the code of Genie Magic objects.
Timers and timer events are features and functionalities in 4DGL programming. These are needed in the implementation of up and down button counters.
Below is a screenshot image of the project used in this application note.
Note 1: The ViSi-Genie project for this application note is “UpDownRepeat”, which is found in Worskhop. Go to the File menu -> Samples -> ViSi Genie Magic (Picaso/Diablo16) -> UpDownRepeat.4DGenie.
Note 2: Workshop Pro is needed for this application.
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.
- 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)
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.
In the past it was not possible to create button counters in ViSi-Genie. With Workshop 4 Pro this is now possible with the use of the Magic Event object. The Magic Event object is under the Genie Magic pane in Workshop 4 Pro. It contains a 4DGL code and it can be linked to standard Genie objects such as a winbutton, such that any time that the button is touched, the Magic Event object is called (or the 4DGL code is executed). The Magic Event object may have a counter variable, the incrementing or decrementing value of which can be used to set the frame value of other objects (a LED digits object for instance). The value can also be sent to an external host.
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:
Two winbutton objects – Winbutton0 and Winbutton1 – are added to Form0.
To know more about winbutton objects, their properties, and how they are added to a project, refer to the application note
A LED digits object is added to Form0. This is Leddigits0.
To know more about LED digits objects, their properties, and how they are added to a project, refer to the application note
A static text object is added to Form0. This is Statictext0.
To know more about static text objects, their properties, and how they are added to a project, refer to the application note
Two magic event objects – MagicEvent0 and MagicEvent1 – are added to Form0.
Also, Winbutton0 is linked to MagicEvent0, and Winbutton1 is linked to MagicEvent1. Going back to the winbutton objects, the Events tabs for each are shown below.
To know more about magic event objects, their properties, and how they are added to a project, refer to the application note
The Magic Event objects in the project for this application note make use of timer events. In 4DGL, a timer event is a process that is executed the moment that a timer, initially set to a certain value, reaches zero. Below is a simple illustration of how a timer event works in 4DGL programming.
Process Y above is the timer event. At some point during the execution of Process X, the timer starts to countdown. When it expires, the program counter leaves process X and goes to process Y. As soon as the program counter is done with process Y, it goes back to process X.
Here are some helpful notes related to timer events:
- The Program Counter of the processor can only attend to one process at a time.
- The timer counts down independently while the Program Counter is executing Process X.
- Process Y directly depends on the timer (its value reaching 0) and not on Process X.
- Process X or any process can initialize the value of the timer and attach or associate to it an event.
- The timer can be stopped anytime by intentionally assigning it a value of zero. In this case, Process Y (the timer event) will not be executed. Any process can stop the timer.
- Any process can reassign the timer a value anytime.
- The event associated to a timer can be changed anytime during runtime.
- In 4DGL there are 8 timers - TIMER0 to TIMER7 - the resolutions of which are all in milliseconds.
Attached is a PDF file (programFlow.pdf) containing four diagrams that attempt to help the user understand how the demo “UpDownRepeat.4DGenie” works. Knowing how timer events work is the key to understanding the diagrams.
In Diagram A there are two classifications of processes – internal and external. Internal processes are those that are performed inside Genie and are hidden from the user. External processes are those that are defined by the user through the use of the magic objects. Of course, all of the processes are actually inside Genie when the entire project is compiled. The processes are classified as such only to facilitate this discussion.
The simplified diagram is self-explanatory. Of course Genie performs other tasks besides those described in this diagram. In summary, Genie calls either MagicEvent0 or MagicEvent1, depending on which button was pressed or released. Genie then passes the status of the button as an argument. Inside the magic event functions, the passed argument is “newval”. The variable “newval” therefore holds the status of the button. Also, MagicEvent0 and MagicEvent1 initiate the execution of other external processes.
The right part of Diagram C is a model for the implementation of two timer events triggered, one at a time, by a timer. After comparing Diagram C to the diagram in the previous section “Timer Events”, the reader will see that MagicEvent0 and MagicEvent1 are both a process X, TIMER0 is the timer, and RepeatUp() and RepeatDown() are both a process Y (timer events).
Since MagicEvent0 and MagicEvent1 work in a similar manner, we will use only MagicEvent0 for this discussion.
First, MagicEvent0 needs to know the status of the button that caused it to be executed. We know this button to be Winbutton0. We also know that its status is passed as an argument. The status is passed to the variable “newval”. If Winbutton0 has been pressed, a sequence of lines are executed. Otherwise, TIMER0 is stopped and control is returned to Genie.
The current value of Leddigits0 is stored as an entry in its image list. To access the current value of Leddigits0, we write
To know more about the function “img_GetWord(…)”, please refer to the Picaso or Diablo16 Internal Functions Reference Manual. Right-click on the 4DGL function name text and choose “Context Sensitive help” to open the manual.
The function “UpdateSend(…)” updates Leddigits0 with a new value.
To know more about the function “WriteObject(…)”,see section 5.1 Genie Magic callable Functions of the ViSi-Genie Reference Manual.
The function “UpdateSend(…)” also sends a message to the serial port.
This function will cause the program to send a REPORT_OBJ message to the serial port. For more information about this function, see section 5.1 Genie Magic callable Functions of the ViSi-Genie Reference Manual.
The 4DGL function for this is
Here TIMER0 is assigned a countdown period of 500 milliseconds. To know more about this function, please refer to the Picaso or Diablo16 Internal Functions Reference Manual. Right-click on the 4DGL function name text and choose “Context Sensitive help” to open the manual.
The 4DGL function for this is
Here RepeatUp() is set as the timer event for TIMER0. When TIMER0 expires, RepeatUp() is executed. To know more about this function, please refer to the Picaso or Diablo16 Internal Functions Reference Manual. Right-click on the 4DGL function name text and choose “Context Sensitive help” to open the manual.
To stop TIMER0 we write:
When TIMER0 is stopped, the timer event attached to it will not be executed.
Note that RepeatUp() is very similar to MagicEvent0(…). Note also that RepeatUp() resets the value of TIMER0 to 100 milliseconds every time.
After analysing the above, the user should be able to conclude that when Winbutton0 is first pressed, MagicEvents0(…) is called. MagicEvents0(…) then updates Leddigits0 and sends a message to the serial port. After 500 ms, RepeatUp() is called. RepeatUp() also updates Leddigits0 and sends a message to the serial port. RepeatUp() is then executed every after 100 ms. However, the moment that Winbutton0 is released, TIMER0 is stopped, and RepeatUp(), therefore, will not be executed. The same operation applies to Winbutton1, MagicEvent1(…), TIMER0, and RepeatDown().
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 send messages 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.
Using the GTX or Genie Test eXecutor tool is one option to get the messages sent by the display 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.
Under the Tools menu click on the GTX tool button.
The Genie Test eXecutor window appears.
On the display module, press and hold the count up button.
The value of Leddigits0 should now increment and REPORT_OBJ messages should be received from the display.
The format of the messages is shown below.
Upon receiving the above messages, the host would know the current value of Leddigits0 and that that it is incrementing.
On the display module, press and hold the count down button.
The value of Leddigits0 should now decrement and REPORT_OBJ messages should be received from the display.
Upon receiving the above messages, the host would know the current value of Leddigits0 and that that it is decrementing.
Modify MagicEvent0(…) to make the program send REPORT_EVENT messages instead of REPORT_OBJ messages. Recompile the project and upload the program to the display module.
On the display module, press and hold the count up button. The value of Leddigits0 should now increment and REPORT_EVENT messages should be received from the display.
The format of the messages is shown below.
Press and hold the count down button. The value of Leddigits0 should now decrement and REPORT_EVENT messages should be received from the display.