Running Touch Diagnostics

Overview > Configuring GUIslice > Touch >

This page details the steps involved in running the diagnostic touch tests

Diagnostics for Arduino

Touch Pin Detection

• Sketch: examples/arduino/diag_ard_touch_detect
• Purpose: Detects pin configuration for simple 4-wire resistive touch displays.
• Output: Settings used in the ADATOUCH_PIN_* configuration values.

Compatibility

NOTE: This pin detection utility does not support ARM or ESP32 / ESP8266 devices.

Operation

• Ensure the Arduino IDE's Serial Monitor window is open.
• Upon running this sketch, the current pin connections between the MCU and the touch overlay are detected. These will be reported via the Serial Monitor.
• 
• A message will indicate whether the current config matches recommendations.
• IF ERROR - Touchscreen is probably broken:
  • The detection utility was not able to find a set of pins that behave like a resistive overlay. Therefore, it is possible that the touch overlay is broken or it has been connected to other pins outside of the detection set.
• IF OK - No need to update config:
  • No changes are required to SECTION 4A of your config file
• IF MISMATCH - Please update config:
  • Copy the ADATOUCH_PIN_* output from the Serial Monitor into SECTION 4A of your config. Save the config.
  • To rerun the diagnostic after updating the config, it is best to close all Arduino IDE windows and then re-open (as sometimes the Arduino IDE caches library settings).
  • Re-upload the diagnostic sketch and run it. This time, it should report that the configuration matches.
• At this point, you can usually proceed to perform the Touch Calibration

Touch Calibration

• Sketch: examples/arduino/diag_ard_touch_calib
• Purpose: Detects touch calibration settings for resistive touch displays
• Output: Settings used in the ADATOUCH_MIN/MAX_X/Y_* configuration values. Visual confirmation that the settings are correct for various orientations (rotation values) of the display.

Background

Resistive touch screens usually incorporate very simple overlays glued to top of the display that provides varying resistance to the touch controller depending on the location of the touch. Usually, 4 pins are used between the overlay and the touch controller, labeled XP, XM, YP and YM. When a touch controller chip is included, it is usually responsible for applying a voltage across pairs of these pins, measuring the resistance values and then reporting them to the MCU (usually via SPI or I2C).

In general, the resistive touch controller does not attempt to translate these resistance values into the corresponding screen coordinates —- this important task is left up to the firmware on the MCU to do. This translation step is called calibration, and involves measuring resistance values at known locations on the display. With this information, a formula can be produced that converts a raw touch reading (resistance) into both the X & Y screen coordinates as well as the touch “pressure” (sometimes referred to as “Z”).

Operation

This sketch will ask the user to touch a number of calibration targets on the screen and then it will report the necessary calibration settings.

After uploading the sketch, the program will guide the user through a number of steps:

• Step 1: general instructions are provided in how to capture the points accurately. In essence, the guidance is to use a stylus or pointed object (not sharp) to press as close as possible to each target, and to hold down on the target for at least 3 seconds so a good reading can be made. Press anywhere on the screen to start.
• Step 2: the first target is shown in the top left of the screen. Press firmly at the center of the target. While pressing, you should see the raw readings (resistance values) shown on the screen, along with the minimum-to-maximum range of these readings. After 3 seconds of firm pressure, release the touch to proceed to the next target.
• Step 3: the next targets will appear in the top-right, bottom-left and bottom-right. Repeat the process until these are captured.
• Step 4: If supported by the display controller, the content on the screen should now rotate clockwise and a final target will be presented in the top-right. This step is very important as it helps GUIslice determine how the touch overlay and screen logical rotation operations match up. Releasing this touch will proceed to the next step.
• Step 5: a read-out will now be presented with the results of the calibration. In most cases, the calibration will be successful and a message to this effect will be shown in green. In some cases, calibration will result in a failure —- please refer to the information provided in the Serial Monitor output for details.
• Step 6: the calibration sketch will now proceed to demonstrate the behavior with the newly-computed calibration values. A red tracer will be shown as the user drags around on the display. If everything is working correctly, then the red dots should align with the location of the stylus. Each time the stylus pressure is released, the display will rotate. It is important to test all 4 orientations of the screen to see that the touch mapping works in all 4 modes.
• Step 7: assuming the calibration was successful, copy the ADATOUCH_X/Y_MIN/MAX values (shown in the serial output) into your configuration file under SECTION 4B.
• Continue to run GUIslice examples with your new calibration settings.

Example of a successful calibration run:

Calibration Issues

• If you receive the error message "Calibration failed", then it usually means that the ADATOUCH_PIN_* settings in the configuration are incorrect.
  • These pin settings define the mapping between the touch overlay pins XP/XM/YP/YM and the MCU, and the error often means that these mappings are swapped or wrong.
  • For the simple 4-wire resistive touchscreens (DRV_TOUCH_ADA_SIMPLE), this can usually be resolved by running the diag_ard_touch_detect diagnostic.

Touch Testing

• Sketch: examples/arduino/diag_ard_touch_test
• Purpose: Demonstrates operation with current touch calibration settings for all displays

Operation

• This sketch simply provides a visual confirmation of the current calibration settings.
• While touching the screen, a red tracer dot should appear under the stylus point.
• Upon releasing the touch, the screen will rotate into the next orientation mode. Again, touch presses in the next orientation will be tested and displayed.
• During the diagnostic, additional details are reported on the screen: X/Y coordinates, touch pressure and the min/max ranges of each.

Diagnostics for LINUX / Raspberry Pi