G2 - Tutorial

G2 - Tutorial

What to consider before starting

Before setting up a project using this software, there are a number of things to consider, the three main ones are:

If this is your first time using this software, it is suggested you pick a hardware combination from the Hardware/Library Support and Feature listing page which has been tested; these are generally a cost effective, versatile choice in most applications anyway. For those more familiar with microcontrollers, you are free to modify the bridge librarys to suit whatever screen you choose. Voltage and SPI bus speeds must be compatible between the screen and the microcontroller
The hardware setup can also determine the touch screen configuration, whether it is polling based, or interrupt based. Polling based is the standard option, and just reads a register in the screen controller chip to determine if a touch event has occured; the same function call updates the display as required, and can return an int to signal which button has been pressed. Hardware interupts should be used when the polling frequency cannot be set high enough, or when the screen controller is not capable of determining if a touch event has occured. In the case ofhardware interrupts, code changes may be required to the bridge-lib or generated code.

This tutorial will use a 5in 800x480 RA8875 controlled display (ER-TFTM050-3) connected to an Arduino Due.
The datasheets for each device show which pins are required. For the screen it is CON1: p1-2 Ground, p3-4 3.3v, p5 CS, p6 SDO, p7 SDI, p8 SCLK and for the Due it is SPI connector, p1 MISO, p3 SCK, p4 MOSI. These match MISO-SDO, SCK-SCLK, MOSI-SDI, CS to a digital output pin, and power connections

Step 1: Hardware Setup

4-Wire SPI communication is used in this example, these are the three hardware SPI pins located in the center of the Due, plus a user specified chip select pin. The 3.3V version of the screen was used, so power was taken from the Due board.

In-program preview
Just 6 Wires and you're good to go, simple jumpers used to show how easy it is

Step 2: Hardware Configuration and Calibration

This next step doubles as a simple test, and a calibration program for the touchscreen. Firstly, test the example program directly, navigate to instal directory\projects\touch calibration\'chose you resolution here'\*Touchcalibrator\ and open the ino sketch file. Ensure the chip select pin (first param on line 10) is set to the one you wired in, and that the reset pin (second param on line 11) is set to a pin not connected to anything else. Then upload the sketch. If it works you will see the same screen on your LCD as previewed. Click on the point in turn to generate the calibration data; repeat if they require refining. Next, we repeat the process bu use the G2 software to generate the files. Start the software and load up the Touch Calibration project to suit your screen resolution (instal directory\projects\...), the project file is the shortest of the three xml documents; the other two have suffixes designating pallete and hardware settings.
Next, go to the edit hardware tab and load the Adafruit Bridging Library (instal dir/BridgeLibs/G2bAdaFruitRA8875) and set the screen height and width; click ok. Then generate the code (file->generate code; ensure it is saved to the same directory that you loaded the sketch from.
Once this is done, and the screen points tapped through, you can enter these values back into the edit hardware screen in G2, it is recomended you then save this (hardware ->save hardware profile) profile so you can quickly load the your screen calibration, size, and selected bridging library for next time.

In-program preview
Photo of LCD with calibration screen

Step 3: Program Design

Finally, the reason you're using this software! Program design is fairly straightforward. Create a new project, load your hardware profile, select a name and save directories based on user preference (marked user detail feilds in figure below); then start dropping buttons and objects in. Buttons and objects can be choosen from the three slide up/down tabs on the left, just click the heading for Input/Output/Misc.
Throughout the process the preview window will offer a preview for what your LCD will look like.
Movig to the right, are the window listings, and full object listings. These are used together to manage and create different window/screens for display. All the objects present in your project will appear in the full object list; they can be deleted using the delete object button. Just above that is the add window button, with multiple windows you can choose what objects appear on each window; this is done using the two object window control buttons to move objects from the full list, to each window, or to remove it from a window. Movig to the right, are the window listings, and full object listings. These are used together to manage and create different window/screens for display. All the objects present in your project will appear in the full object list; they can be deleted using the delete object button. Just above that is the add window button, with multiple windows you can choose what objects appear on each window; this is done using the two object window control buttons to move objects from the full list, to each window, or to remove it from a window.
The Object property editor takes up most of the lower screen, this is where the look and action of each object can be changed. It is important to note changes are only saved when the enter button is pressed in the text box! Each parameter can be selected, and modified accordingly. The position and click area (usually copied from object dimensions) can be modified using spinboxes. The default colors come from the pallette, which can be edited, saved, etc similarly to the hardware profiles; or simply used as a color picker to change individual buttons. Colors are stored as a single long integer for simplicity. Text font and justification are only partially implemented at the moment, due to some libraries not supporting software fonts. Most other properties are self explanatory, or can be seen with trial and error.
The final, and one of the more advanced sections is the user code entry box. This is where you can store variables, and commands to be run once the variable is changed. Code like:
int WindowState=0;stateUpdateObjects(WindowState) can be used to monitor the WindowState variable, and use the library function stateUpdateObjects to change the window. Buttons can be used to set the WindowState variable like so @@.ObjectState=2;@@.drawByState();WindowState=1; in this code, the first two items change the state of the button being pressed (@@ is shorthand to reference the object calling the action; @x@ is shorthand to reference object with x id number); while the third sets the WindowState variable to 1.
Both these blocks of code work together (and are all that is needed) to change window/screens, the first item in the user code line sets the default value of WindowState, and also holds a previous WindowState variable in memory. Each time the display function is called, touchscreen events are checked and processed, then these two variables are compared for changes. If it has changed, the remaining part of that line is called; in this case, to change the window/screen state.
The user code area can contain quite complex statements, including if, switch, for, etc. It cannot contain blocking statement, and it must be on the same line (this constraint may be removed in future if there is demand). This should give a basic overview of how the layout functionality works, gaps should be able to be filled in by trial and error, or discussion on the forum. Save the files, generate the code, and move on to the final step.

In-program preview
In-program preview

Step 4: Required Code

For this example we'll use the Arduino IDE, and add the bare minimum amount of code required to get a working screen. First step is to create the .ino file in the directory, must be named the same as the directory name. Alternatively, save the .ino file then point the G2 generation path to that save directory. In either case, the IDE will need to look like the calibration example, with the main .ino file, and two pairs of .h/.cpp files for the bridging library, and the generated files; for a total of 5 tabs open. The .ino file itself will look like this:

          #include <SPI.h>
          #include <Adafruit_GFX.h>
          #include <Adafruit_RA8875.h>
          #include "G2BAdaFruitRA8875.h"
          #include "TouchCalibrationGen.h"

          TouchCalibrationGen screenClass;
          Adafruit_RA8875 tft = Adafruit_RA8875(A6, A4);
          G2bAdaFruitRA8875 LCD=G2bAdaFruitRA8875(&tft,RA8875_800x480);

          void setup() {
          LCD.initBridge();
          screenClass.initTFT(&LCD);
          }

          void loop() {
          screenClass.displayScan();
          delay(10);
          }
        
        

A number of includes are required, the SPI library which comes with the IDE, and the two Adafruit libraries required to run the RA8875 chip. The next two are the files included in the project directory, the bridging library which is copied across, and the the generated file specific to the poject.
Global variables are also used, the screenClass is defined from the generated file. An instance of the included libraries Adafruit_RA8875 which requires the pins be passed as parameters, similarly to above, the first must be the Chip Select line, with the second being any unused pin. An instance of the bridging library G2bAdaFruitRA8875 must be created, and a pointer to the Adafruit_RA8875 instance passed to it.
In the setup method, the bridge must be initialised, and the screenClass after that. screenClass.initTFT has a second argument to set the starting screen which defaults to 0.
In the loop all we need to do is call the display scan line. This takes care of all touch and screen events; it can return an integer if required (just put 'return 1;' in a user code line, or in the 'On Click' or 'On Release' feilds). To prevent saturation of the SPI bus a small delay between function calls is required, obviously this can be removed when the functions in the loop require significant time to process.

note: as befitting the alpha nature of the project, this tutorial process is subject to change, and may not be complete. I will endevour to support this project by monitoring the the forums and updating the software and documentation as required.

Links