Readme

Basic Instructions of Repository DisplayESP32

This repository aims to provide some functions for creating a user interface for the display Adafruit SSD1306 on microcontroller ESP32.
For such, new classes are implemented, which are included in the .ino code included in this repo.

To begin with

To be able to use this repository, it's important to first connect the display to the microcontroller correctly. The following diagram shows how it should be done when using an ESP32-WROOM board.

It is possible to see that the display used in this project uses I2C protocol, thus only two pins are needed to allow communication with the microcontroller.
On the other hand, the keyboard uses one pin for each button (configured as Pull up), and a connection to Ground.

Macros

Macros are defined to help use the library easily, making possible to modify the display specs in an easy way and also, the behaviour of the interface, by just changing the values defined.

#define MAX_OPTIONS 10      //Maximum number of options for each menu
#define MAX_MENUS 3
#define MAX_GRAPH 3
#define DISP_WIDTH 128      // OLED display width
#define DISP_HEIGHT 64      // OLED display height
#define REFRESH 10          //Refresh time in ms

• MAX_OPTIONS defines the maximum number of options a menu can hold, in this case, there can only be three menus in total, as there is only enough memory reserved for them.
• MAX_MENUS declares the maximum number of menu screens in the interface, it's not possible to create more menus than this number.
• MAX_GRAPHS is the maximum number of graphs to create.
• DISP_WIDTH and DISP_HEIGHT are hardware specific (SSD1306), it's possible to modify this values in the case that it's required to employ a different kind of display.
• REFRESH is the time in milliseconds the interface will take in refreshing (this time affects the loop, keep that in mind)

Content types

Classes

In this section, the created classes are discussed, to better understand how each of them works.

Before getting into the next classes, it's necessary to note that most methods in them aren't supposed to be accessed directly, there are methods in the classes Screen and Keyboard that use them to control the interface through their own methods, which end up calling those in each class but also control the behaviour of the display at the same time, which allows for less code lines when using the library to program an interface.
Despite the above, the methods in each class will be presented to better know how they work.

Option class

This class is implemented to create options that will be later used to conform a menu.

Attributes

The attributes of this class are:

private:

int sizex;
int sizey;
String content;
int pos;
int textSpacing;   //According to the height, defines the space for the text, so that it's vertically centered
bool fill = false;  //In case an option is not selected this should be false
bool disp = false;   //In case an option is not configured, it should be false and, thus hidden
int destinationType;   //Defines what the option leads to (another menu, graph, something else)
int destinationIndex;  //Defines where the option leads to (index of the destination)

• sizex: Defines the size the option will occupy in the x axis (width), this value is gotten from the menu. Menu class has an attribute that defines the size it will have in the x axis.
• sizey: Defines the height of the option (this value is gotten from the menu it belongs to).
• content: This string corresponds to the caption the option will display once created.
• pos: Integer that defines the position it has in the menu.
• destinationType: Used to know what type of screen the option leads to (menu, graph, etc...).
• destinationIndex: Used to know what index the destination screen has, leading only to that screen.

It is important to note that indexes are assigned according to the order the screen was created, if it is the first screen created, then its index is 0.

Methods

The following are the methods used to interact with each option created.

configure()

This method assigns the values to the option created, according to the way it's containing menu is defined and the parameters we want for such option as is its destination. This method shouldn't be called on its own, because class Screen already has one method to create options and assign them to a specific menu. The prototype for this method is:

void configure(String content, int sizex, int sizey, int pos, int destinationType, int destinationIndex)

getDestinationType() and getDestinationIndex()

Methods accessed by others from Screen class. These return and integer corresponding to the type and index of the screen they lead to. It's not needed to call this methods directly, there are functions that do that and update the screen at the same time.

drawOpt()

With this method, an option is drawn. This is another method that shouldn't be called directly, as there are other methods in the next classes that call it for all the options in a menu.
This function requires the parameters shown in its prototype:

void drawOpt(int page, int pos, int optPPage)

These parameters are obtained automatically from the method drawMenu in Menu that draws all the options within it. In this method, if the option is selected, then it will be printed in a filled rectangle, otherwise, it will appear as a black rectangle.

Menu class

This class is used to create menus and keep their attributes stored throughout the use of the interface.

Attributes

The following attributes belong to this class:

private:

int sizex;
int sizey;                  //Y size of each option in the menu
int options = 0;            //This indicates the number of options created
int pos = 0;                //This indicates the position of the cursor
int page = 0;               //If the menu is too long, this indicates the page that is being displayed
Option opt[MAX_OPTIONS];
int optPPage;

int previousScreen = 0;
int previousContentType = 0;

Where:

• sizex: Defines the width of the options, it's preferable to leave this option as DISP_WIDTH or 128, since it will cover the whole display width.
• sizey: Defines the height of each option in this menu, a value of 13 grants a good visualization of each option, greater values improve spacing, reducing the number of options per page though.
• options: This acts as a counter that stores the number of options created in the menu.
• pos: This variable stores the position of the menu in which the user is at a certain time.
• page: According to the number of options per page (optPPage), this variable holds the page to be printed in larger menus.
• Option opt[MAX_OPTIONS]: This is an array that holds every option created in the menu (with a maximum of MAX_OPTIONS).
• previousScreen and previousContentType: These integers keep the values of the screen that led to this menu, to make it possible to return to that screen. This values are assigned from a method in Menu, called from another one in Screen, which is used to control the interaction with the interface. This will be discussed later in this document, see Screen class.

Methods

Now, we'll talk about the methods included in this class.

configure()

To create a menu, it's important to configure it first. That's where this method is applied, though not directly, since there is another method in Screen that calls for this method and creates a menu for the interface. The prototype for this method is as follows:

void configure(int sizex, int sizey)

From the height of each option, it is possible to determine the number of options by each page of the menu. As a result, in this method, optPPage is assigned too.

createOption

This method is in charge of adding options to the menu. It recurs to the method configure in Option and assigns the values for the size, position and destination. The prototype is the shown next:

void createOption(String content, bool destinationTypeMenu, int destinationIndex)

The parameters are received from the method in Screen to create an option for a menu.
As we can see in the next line, the option receives a position according to the number of options currently in the menu, then the variable is increased because there is one more option.

this->opt[this->options].configure(content, this->sizex, this->sizey, this->options++, destinationTypeMenu, destinationIndex)

Furthermore, the option is assinged to a place in the array of options.

extractDestinationType() and extractDestinationIndex()

Both methods are used to get the integers corresponding to the destination of the option selected, which serve to interact with the interface, allowing the user to enter an option of the menu and change from screen to screen.

drawMenu()

drawMenu() is used to draw all the options in the menu. It draws only the options that have been configured, thus ignores those within the array opt that haven't been used. To draw the options, it is important to provide the parameters for the drawOpt() method in Option, which are page, pos and optPPage, so first we get the page by getting the options per page, optPPage is calculated according to sizey, defined at the creation of the menu (this calculation takes into account the macro DISP_HEIGHT, discussed previously), pos is the attribute of the menu, which stores the current position of the cursor (option to display as selected by user). All the above is shown in the next lines:

void drawMenu(){
    display.clearDisplay();
    this->page = pos/this->optPPage;
    for(int i = 0; i < options; i++){
    this->opt[i].drawopt(this->page, this->pos, this->optPPage);
    }
    display.display();
}

In configure():

this->optPPage = DISP_HEIGHT / this->sizey;

extractPos() and extractOptNumber()

These methods are only used to extract values from the attributes of the objects of Menu. These data will be useful for knowing where the cursor is in regards to the number of options in the menu. That way, it's possible to prevent the cursor from moving beyond the options in the menu. These will be used in another method from Screen.

increasePos() and decreasePos()

These methods are accessed by Screen in order to increase or decrease the position of the cursor, since Screen serves as the controller of the whole interface, and keyboard interacts directly with its methods.

Previous screen storing

In order to store the previous screen, it's necessary to store the values that lead to it, both, index and type of content, thus four methods are implemented for that, two of them retrieve the values of the actual screen before changing to the new menu, the other two methods are called to store them in the latter, modifying the attributes previousScreen and previousContentType.

setPreviousScreen(int previousIndex) and setPreviousScreenType(int previousScreenType) store the values of the previous screen passed from a Screen object, making it possible to go to the next menu and update the current Screen attributes, without losing the data of the previous screen.

getPreviousScreen() and getPreviousScreenType() retrieve the data from previousScreen and previousScreenType, allowing the transition to a previous menu.

Graph class

This class is for the creation of graphs. It allows the ploting of three types of graphs: vertical bar, horizontal bar and cartesian chart.

Attributes

To achieve the above stated the following attributes are used:

private:

String title;
char graphType;       //'a' Vertical Bar, 'b' Horizontal Bar, 'c' Cartesian Graph

//Assign whatever value in "configure(..." if a parameter is not required for the specified graphType

double value;         //For: Vertical Bar  Horizontal Bar  Cartesian
double xpos;          //For: Vertical Bar  Horizontal Bar  Cartesian
double ypos;          //For: Vertical Bar  Horizontal Bar  Cartesian
double height;        //For: Vertical Bar  Horizontal Bar  Cartesian
double width;         //For: Vertical Bar  Horizontal Bar  Cartesian
double yminimum;      //For: Vertical Bar                  Cartesian
double ymaximum;      //For: Vertical Bar                  Cartesian
double xminimum;      //For:               Horizontal Bar  Cartesian
double xmaximum;      //For:               Horizontal Bar  Cartesian
double yStepSize;     //For: Vertical Bar                  Cartesian
double xStepSize;     //For:               Horizontal Bar  Cartesian
int digit;            //For: Vertical Bar  Horizontal Bar  Cartesian
double x;
double yrange;
double xrange;
double ox;
double oy;
double count;
double graphScale;
bool redraw = true;

int previousScreen = 0;
int previousContentType = 0;

• title: This string allocates the name of the graph to be displayed at the top of the display.
• graphType: The type of graph created 'a' means a vertical graph, 'b' a horizontal graph and 'c' a cartesian chart.
• value: It's the value to pass to the graph, there is method for that. This attribute is used by all types of graphs.
• xpos: This is the position in x of the bottom left corner of the graph. Required by all graph types.
• ypos: This is the position in y of the bottom left corner of the graph. Required by all graph types.
• height: Height of the graph (pixels).
• width: Width of the graph(pixels).
• yminimum: This is the minimum value to be graphed in the y axis. Required only for vertical graph and cartesian chart.
• ymaximum: Maximum value to graph in the y axis. Required only for vertical graph and cartesian chart.
• xminimum: This is the minimum value to be graphed in the x axis. Required only for horizontal graph and cartesian chart.
• xmaximum: Maximum value to graph in the x axis. Required only for horizontal graph and cartesian chart.
• yStepSize: Size of the step in the y axis. This is the interval in which the axis is going to be split. Required only for vertical graph and cartesian chart.
• xStepSize: Size of the step in the x axis. This is the interval in which the axis is going to be split. Required only for horizontal graph and cartesian chart.
• digit: Number of decimal digits to display in the axis labels.
• x: This is used to know the ending point of a line in the cartesian chart.
• yrange: Range in the y axis, depends on the maximum and minimum of this axis.
• xrange: Range in the x axis, depends on the maximum and minimum of this axis.
• ox: Starting point in x of a line to plot in the cartesian chart (Previous x value).
• oy: Starting point in y of a line to plot in the cartesian chart (Previous value received).
• count: Last iteration of the cartesian chart, in the x axis.
• graphScale: Scale of the graph (vertical or horizontal), according to its minimum and maximum.
• redraw: This boolean should only be true then the whole screen was cleared. It redraws the axes or the bars respectively.
• previousScreen and previousContentType: These integers keep the values of the screen that led to this graph, to make it possible to return to that screen. This values are assigned from a method in Graph, called from another one in Screen, which is used to control the interaction with the interface. This will be discussed later in this document, see Screen class.

Methods

The following methods are applied to manage data from Graph.

configure()

This method sets up the new graph, its main attributes are defined here. The parameters passed in this case include all the attributes required for any kind of graph, however, as stated in some other methods, this one should not be called, there are some methods in Screen that call for this method and only require the parameters necessary for a certain type of graph (createVGraph(), createHGraph(), createCGraph()), these will be explained later.

Screen class

Keyboard class

Implementation