-
Notifications
You must be signed in to change notification settings - Fork 315
thelloworld
- How to setup U8glib for a display?
- How to put a simple message on the display with U8glib?
Once the display is physically connected to an Arduino Board three steps are required to bring some graphics on the display:
- Call an U8glib constructor (selected from here)
- Add the "picture loop"
- Write a graphics "draw" procedure
There is not only a single constructor for U8glib. Instead please select a specific constructor for display or display controller (see here). In some cases a display, which is not listed, might also work if just the controller matches. For example
U8GLIB_DOGM128 u8g(sck, mosi, cs, a0 [, reset])
might also work for other displays than the dogm128 display, if the controller (ST7565) matches.
The controller also needs to know, how the display is connected to the Arduino pins. The corresponding pin numbers must be applied as arguments to the constructor. See also the tutorial about the setup of the display hardware.
U8glib offers to control the reset line of the display. If the reset input of the display is wired to a pin of the Arduino board, then this pin-number can be set here. U8glib then will take care on the proper reset of the device.
U8glib needs a special programming construct, called "picture loop". It can be usually placed in the loop() procedure of the Arduino Sketch:
void loop(void) {
// picture loop
u8g.firstPage();
do {
draw();
} while( u8g.nextPage() );
// rebuild the picture after some delay
delay(1000);
}
The full picture of the graphics device is drawn by looping through the picture loop. The body of the picture loop contains a list of graphic commands. It usually makes sense to place the graphics commands into their own procedure (in this example: draw()
).
More information on the picture loop is described here.
Best practice is to place all graphics commands into one procedure (draw()
):
void draw(void) {
// graphic commands to redraw the complete screen should be placed here
u8g.setFont(u8g_font_unifont);
u8g.drawStr( 0, 20, "Hello World!");
}
There are a lot of graphics commands. All of them are listed in the User Reference Page of U8glib.
u8g.setFont(u8g_font_unifont);
The first command in this little example selects a font. All fonts start with u8g_font_
. Fonts can be selected by their size or by their origin.
u8g.drawStr( 0, 20, "Hello World!");
The second command writes a string to the display. The first two arguments define the position on the screen. The drawStr
procedure uses the previously selected font and will use the current color index (defaults to 1) to render the string on the display.
There are some restrictions on this draw()
procedure (picture loop). This restrictions are explained in more detail here. From a programming perspective this means for the draw()
procedure (picture loop):
- Do not modify global variables from inside the
draw()
procedure. - Do not declare
static
variables inside thedraw()
procedure. - Assume a cleared and empty screen at the beginning of the
draw()
procedure. - Internal values like draw color or current font should be set at the beginning of the
draw()
procedure. - Internal values like draw color or current font can be set outside the picture loop, if they are not changed within the picture loop. On the other hand, the following is fine (and often required):
- Read values from global variables or use arguments to the
draw()
procedure. - Use local variables,
if
conditions and loops (for
,while
) within thedraw()
procedure.
For example, do not do the following:
int y_pos = 0; // global variable
void draw(void) {
// graphic commands to redraw the complete screen should be placed here
u8g.setFont(u8g_font_unifont);
u8g.drawStr( 0, y_pos, "Hello World!");
y_pos++; // Wrong: Global variable modified inside picture loop / draw()
}
If you would like to program an animation which increases the y-position for each picture, then increase y_pos
outside the picture loop:
int y_pos = 0; // global variable
void draw(void) {
// graphic commands to redraw the complete screen should be placed here
u8g.setFont(u8g_font_unifont);
u8g.drawStr( 0, y_pos, "Hello World!");
}
void loop(void) {
// picture loop
u8g.firstPage();
do {
draw();
} while( u8g.nextPage() );
// Correct: Increase y_pos outside the picture loop
y_pos++;
// rebuild the picture after some delay
delay(1000);
}
- Use the correct constructor to setup the display (see here).
- Place graphics commands inside the picture loop.
- Group your graphics commands into a procedure (e.g.
draw()
). - Please note the restrictions for the picture loop.