ViSi-Genie Arduino The Slider Object

4D Systems Codebase Example

Introduction


Setup

This codebase example demonstrates how to write a sketch, using the ViSi-Genie-Arduino library, for a program that will make an Arduino host communicate with slider objects on the display module. More specifically, this codebase example demonstrates how to create a basic Arduino program that will handle events (REPORT_EVENT and REPORT_OBJ) coming from the display module. The program will also send WRITE_OBJ and READ_OBJ messages to the display module.

The uLCD-32PTU

This codebase example uses an Arduino Uno as the host and a uLCD-32PTU as the display module. The latest version of the Arduino IDE was used in compiling the attached sketch. The Uno uses a software serial port to communicate with the display module. It uses the hardware serial port Serial0 to communicate with the Serial Monitor of the Arduino IDE. The Uno prints to the Serial Monitor information regarding the states of the objects on the display. The user can also input a sequence of alphanumeric characters to instruct the Uno to change or query the state of any of the objects.

The Arduino Uno

Prerequisites

This codebase example assumes that the reader has read and understood the codebase example ViSi-Genie GTX The Slider Object. A working knowledge of the Arduino platform is also required. Users who are not familiar with the basics of interfacing an Arduino host to a 4D display module may refer to the application note ViSi-Genie Connecting a 4D Display to an Arduino Host.

Hardware Setup


This codebase example uses the 4D Arduino Adaptor Shield (rev 2.0) to interface the uLCD-32PTU to the Arduino Uno.

4D Arduino Adaptor Shield (rev 2.0)

The RX pin (of jumper J3) of the 4D Arduino Adaptor Shield is connected to pin 10 of the Uno. The TX pin (of jumper J4) is connected to pin 11 of the Uno.

Adaptor + uLCD+32PTU + Uno

This effectively connects the serial port of the display module to the software serial port being used by the Uno (as configured in the attached Arduino sketch). For more information, refer to the 4D Arduino Adaptor Shield (rev 2.0) datasheet and to the application note ViSi-Genie Connecting a 4D Display to an Arduino Host.

Adaptor + Uno

How the Program Works


Below are some pointers on how the program running on the Arduino host works.

Evaluate a REPORT_EVENT Event

The ViSi-Genie-Arduino library internally receives and buffers all events coming from the display module. In the event handler of the sketch, all that we have to do is get an event from the buffer or queue and evaluate it.

if (Event.reportObject.cmd == GENIE_REPORT_EVENT)
{
  if (Event.reportObject.object == GENIE_OBJ_SLIDER)  // If the REPORT_EVENT Message was from a slider
  {
    slider_val = genie.GetEventData(&Event);          // Receive the event data from the object

    if (Event.reportObject.index == 0) {              // If from Slider0
      // do something
    }

    else if (Event.reportObject.index == 1) {         // If from Slider1
      // do something
    }

    //else
    //unhandled event
  }
}

Evaluate a REPORT_OBJ Event

The routine is similar for a REPORT_OBJ message or event.

if (Event.reportObject.cmd == GENIE_REPORT_OBJ)
{
  if (Event.reportObject.object == GENIE_OBJ_SLIDER)  // If the REPORT_OBJ Message was from a slider
  {
    slider_val = genie.GetEventData(&Event);          // Receive the event data from the slider object
    //Serial.print("\n");
    if (Event.reportObject.index == 0) {              // If from Slider0
      // do something
    }

    else if (Event.reportObject.index == 1) {         // If from Slider1
      // do something
    }

    else if (Event.reportObject.index == 2) {         // If from Slider2
      // do something
    }

    //else
    //unhandled event
  }
}

Send a WRITE_OBJ Message

To send a WRITE_OBJ message to the display, we use the "WriteObject()" method of the ViSi-Genie-Arduino library. The prototype of the "WriteObject()" method is shown below.

uint16_t WriteObject(uint16_t object, uint16_t index, uint16_t data);

The argument "object" identifies the type of object (e.g. a slider, a button, a user LED, etc.). The argument "index" identifies the index of that object (e.g. Slider0, Slider1, Slider2, etc.). The argument "data" is the value to be written to the object. Note that the return value is not used. To force the state of Slider0 to 1 for instance, we would write,

genie.WriteObject(GENIE_OBJ_SLIDER, 0, 1);

A list of all the object ID constants (e.g. "GENIE_OBJ_SLIDER" for a slider object) can be found in the library header file "genieArduino.h".

Send a READ_OBJ Message

To send a READ_OBJ message to the display, we use the "ReadObject()" method of the ViSi-Genie-Arduino library. The prototype of the "ReadObject()" method is shown below.

bool ReadObject(uint16_t object, uint16_t index);

The argument "object" is the type of the object whose state is being queried. The argument "index" is the index of that object. Note that the return value is not used. To query the state of Slider2 for instance, we would write,

genie.ReadObject(GENIE_OBJ_SLIDER, 2);

The display would then reply with a REPORT_OBJ event, which would then be buffered by the library and processed by the user-defined event handler.

User Input to the Serial Monitor

Note that the sketch was written such that the user can initiate the sending of WRITE_OBJ and READ_OBJ messages to the display module by typing a certain combination of alphanumeric characters to the Serial Monitor. To get the Arduino host to send a WRITE_OBJ message with the value "10" to Slider2 for example, we would type "write 2 10" to the input text box of the Serial monitor and then press the send button.

send a WRITE_OBJ

The Serial Monitor would then print a message saying that the WRITE_OBJ message has been sent.

send a WRITE_OBJ

As can be seen in the sketch, this would be equivalent to the host executing the line

genie.WriteObject(GENIE_OBJ_SLIDER, 2, 10);

The display module should then update the state of Slider2 accordingly. The same process applies for sending a READ_OBJ message to the display module. Hence, the general process is as follows.

  1. First the user inputs the correct sequence of alphanumeric characters to the text box of the Serial Monitor and presses the send button.
  2. Second, the program parses the character sequence, extracts the parameter or parameters, and passes them to the correct method ("genie.WriteObject(...)" for a WRITE_OBJ message and "genie.ReadObject(...)" for a READ_OBJ message). The method is then executed.
  3. For a WRITE_OBJ message, the Serial Monitor should print the state and index of the object whose state has just been changed. The display module should also update the state of the object accordingly.
  4. For a READ_OBJ message, the Serial Monitor should print the state of the object whose state is being queried.

The various possible combinations of alphanumeric characters to be entered to the text box of the Serial Monitor for this demo are listed in the attached file "valid commands.txt". The use of the input text box of the Serial Monitor as a means for the user to initiate the sending of WRITE_OBJ and READ_OBJ messages to the display module was chosen to avoid the addition of other objects to the display program. Hopefully, this makes the example simpler and focused on a particular object only.

To parse the sequence of characters entered by the user to the Serial Monitor, additional functions were added to the sketch. These are "serialEvent()", "evaluateMessage(...)", "getIndex(...)", and "getValue(...)". Discussion of how these functions work, however, is not really within the scope of this document.

Modifying/Improving this Example

This example was configured such that users can run it on a minimal hardware setup - an Arduino Uno which uses its single hardware serial port for communicating with the Serial Monitor of the Arduino IDE and a software serial port for communicating with the display module. The software serial port however has its limitations which would compromise the performance of applications that make intensive use of the serial communication link. For this reason, users who intend to use or improve further this codebase example for bigger projects are encouraged to use a hardware serial port of the Arduino host when interfacing it to the display module. This way, the baudrate can be increased further. Also, uncaught events coming from the display module would also be avoided. Note that the Arduino Uno has only one hardware serial port, while the Mega and Due have four hardware serial ports available. Visit the Arduino website for more information.

To use a hardware serial port (e.g. Serial1) to communicate with the display module, modify lines 35 and 36 of the attached sketch like as shown below:

Serial1.begin(9600);  
genie.Begin(Serial1);

The baudrate could then be increased up to 200000 bps.

Serial1.begin(200000);  
genie.Begin(Serial1);

Note that the baudrate configuration of the corresponding ViSi-Genie project should also be updated accordingly to match that of the Arduino sketch/program. Of course the TX and RX lines of the display module should also be properly connected to the RX and TX pins of the host's selected serial port. All lines related to the use of the software serial port could then be removed from the Arduino sketch. For more information, refer to the application note ViSi-Genie Connecting a 4D Display to an Arduino Host.

A major revision of the attached sketch would be needed for users who intend to interface the display to the hardware serial port Serial0 of the Arduino host. As mentioned above, this example uses Serial0 to print information to the Serial Monitor of the Arduino IDE. Hence, Serial0 cannot be used to communicate with the display module, unless the sketch is modified.

Project File(s)


The Arduino sketch file and "valid commands.txt" are inside the folder "Arduino Sketch".

Arduino Sketch Text File
SlidersSS_R_1_0.ino valid commands.txt

Instructions


Follow the procedure below to run this example. The reader is also advised to watch the accompanying video. Note that before proceeding to step 1 below, the ViSi-Genie program desribed in the codebase example ViSi-Genie GTX The Slider Object should have been loaded to the display module already.

  1. Open the attached sketch in the Arduino IDE, compile it, and upload the program to your target Arduino board (an Arduino Uno for this codebase example).
  2. Properly connect the Arduino Uno to the uLCD-32PTU. Note that in this codebase example, the 4D Arduino Adaptor Shield (rev 2.0) was used.
  3. Open the Serial Monitor of the Arduino IDE.
  4. The application should now run. Watch the accompanying video and follow the test procedure shown.

If not familiar with the details of the steps above, see the application note ViSi-Genie Connecting a 4D Display to an Arduino Host.


Property Details
Number 4D-CD-00069
Revision 1.00
Author 4D Systems
Difficulty easy
Tested on a uLCD-32PTU
Relevant 4D Product/s All Picaso and Diablo16 touch displays
Workshop 4 Environment ViSi-Genie
Recommended Codebase Examples ViSi-Genie GTX The Slider Object
Relevant Application Notes ViSi-Genie Connecting a 4D Display to an Arduino Host.
Relevant Projects NA
Relevant Workshop 4 IDE Examples NA