ezLCD+103 Driver
0.1
Driver code for the ezLCD+103
|
Enumerations | |
enum | ezLCD_button_state_t { EZLCD_BUTTON_UP = 1, EZLCD_BUTTON_DOWN, EZLCD_BUTTON_DISABLED, EZLCD_BUTTON_INVISIBLE } |
enum | ezLCD_touch_protocol_t { ezButton = 1, cuButton = 2, calibratedXY = 64 } |
Functions | |
void | ezLCD_button_define_long (uint8_t id, ezLCD_button_state_t state, uint16_t index_up, uint16_t index_down, uint16_t index_disabled, uint16_t x, uint16_t y, uint8_t width, uint8_t height) |
void | ezLCD_set_touch_protocol (ezLCD_touch_protocol_t protocol) |
void | ezLCD_set_button_state (uint8_t id, ezLCD_button_state_t state) |
void | ezLCD_calibrate_screen () |
void | ezLCD_deactivate_all_buttons () |
void | ezLCD_all_buttons_up () |
uint8_t | ezLCD_wait_for_event () |
This header contains functions used for configuring, placing, and polling buttons on the screen. It is strongly recommended that the user read section 4 of the ezLCD External Commands manual before continuing
As the manual states; there are three different ways one can interact with the touch capabilities of the display. Each touch protocol (ezButton, cuButton, or calibratedXY) have different which may be desirable for different applications. Before the touch screen can begin sending data the user must first choose a button protocol
The ezButton protocol only sends data back to the screen when an event occurs. There are two types of events: when a button is pressed and when a button is released. The ezButton only broadcasts these events ONCE when it occurs and never again (until it occurs again). This is the recommended protocol for new users since it is the easiest one to work with. The data packet sent by the display at the occurrence of an event contains two parts: an ID number and a state as shown below.
In the case of the cuButton, there are also two kinds of events: button down and no button pressed. The cuButton event packet is shown below.
When no button is pressed, the entire packet (status and ID fields) will contain all logic 1's. Otherwise, when a button is pressed, the status bits will be 01 and the ID number is dependent on the ID number chosen by the ezLCD_button_define_long() function.
Once the user has selected a protocol, only then may they begin to place buttons on the screen. If the user places buttons on the screen before setting a protocol, the buttons may be inoperable and may need to be redrawn. See the ezLCD_button_define_long() documentation for insight on button images and placement.
Once a touch protocol has been selected and a button is placed on the screen (in the case of ezButton and cuButton), we are ready to begin sensing events. Unfortunately, the only way to detect button or screen presses is by polling the SPI data register. There is no additional signal that can be used for interrupts. So in order to determine when a button has been pressed, the user must send no-op commands (the number 0) to the screen on the MOSI line and then read the data that comes back on the MISO line. This is demonstrated by the ezLCD_wait_for_event() function.
After receiving data from the display, the microcontroller must choose what to do based on which button was pressed or what portion of the screen was pressed. While there may be other external activities (such as lighting an LED) that should be performed at the touch of the screen; one must realize that the ezLCD does not automatically replace the EZLCD_BUTTON_UP image with the the EZLCD_BUTTON_DOWN image or vice-versa. Again, read the documentation for ezLCD_button_define_long() if you do not understand what these states are. Upon receiving an event packet, the microcontroller must then instruct the ezLCD to replace the EZLCD_BUTTON_UP image with the EZLCD_BUTTON_DOWN image or vice-versa using the ezLCD_set_button_state() function.
enum ezLCD_button_state_t |
Enumerated types used by the ezLCD_set_EZLCD_BUTTON_state() and the ezLCD_button_define_long() functions to defining a button state.
Enumerated types used by the ezLCD_set_touch_protocol() function to determine the button mode.
void ezLCD_all_buttons_up | ( | ) |
This function places all buttons in their UP state and consequently draws their EZLCD_BUTTON_UP images to the screen.
void ezLCD_button_define_long | ( | uint8_t | id, |
ezLCD_button_state_t | state, | ||
uint16_t | index_up, | ||
uint16_t | index_down, | ||
uint16_t | index_disabled, | ||
uint16_t | x, | ||
uint16_t | y, | ||
uint8_t | width, | ||
uint8_t | height | ||
) |
Defines a button and places it on the current frame.
A button consists of an ID, up to three images, an XY coordinate, and a width and height.
In order to specify the touch zone of the button, we must tell the display how wide and tall we want this area to be. Our button images may be larger or smaller than these numbers.
NOTE: Just because a button was placed on the drawing frame and not the display frame does not mean that the button is not active. The button will still be active and will still respond to touch in its area of placement even if it is not visible on the screen because it has been placed on another frame.
void ezLCD_calibrate_screen | ( | ) |
This function sends a command to the screen to enter its built in calibration routine and then waits until the screen has been successfully calibrated.
void ezLCD_deactivate_all_buttons | ( | ) |
This function deactivates all buttons so that they no longer respond to touch. However, it does not remove their image from the screen or frame.
void ezLCD_set_button_state | ( | uint8_t | id, |
ezLCD_button_state_t | state | ||
) |
Sets the display state of a button and therefore changes the button's image on the screen (if supplied).
void ezLCD_set_touch_protocol | ( | ezLCD_touch_protocol_t | protocol | ) |
Sets the touch protocol for the entire screen. That is, this setting applies to all buttons placed on the screen and not just one button.
uint8_t ezLCD_wait_for_event | ( | ) |
This function is provided as an example of how one can poll the screen for button events. When called, this function waits indefinitely for a button to be pressed and then released before returning. The function changes button state image in accordance with the button's status. So when any button is pressed, it will paint that button's EZLCD_BUTTON_DOWN image to the screen in place of its EZLCD_BUTTON_UP image. It will do the opposite when the button is released and only then will it return the pressed button's ID. IT IS STRONGLY RECOMMENDED THAT THE USER STUDY THIS FUNCTION IN DEPTH SO THAT THEY MAY WRITE THEIR OWN FUNCTIONS TO DETECT BUTTON PRESSES SINCE THIS FUNCTION MAY NOT BE SUITABLE FOR ALL APPLICATIONS. This function only works with the ezButton protocol.