t01u8g

Tutorial 1 (U8g library): Hello World Example

This tutorial will show:

• How to display some text on the LCD
• The three parts in your program to setup m2tklib for the U8g library within an Arduino Environment

Theory

The purpose of the m2tklib is to interact with the user. M2tklib reads button events (see also Tutorial 2) and displays something on an output device. This first example will display a small text on the LCD. Four parts are required:

• Define the output for the Graphics-Device. This is called an element tree.
• Assign the root element of this element tree to the library and define a display style for the output device
• Connect U8g graphics library to M2tklib
• Draw the element hierarchy on the output device.

Example

Reference: HelloWorld example.

The following example is simplified and only includes code, which is related to the m2tklib itself:

// ...
#include "M2tk.h"
// ...

M2_LABEL(hello_world_label, NULL, "Hello World");
M2tk m2(&hello_world_label, NULL, NULL, m2_gh_u8g_bfs);

void setup() {
  // ...
  m2_SetU8g(u8g.getU8g(), m2_u8g_box_icon);
  // ...
}

void loop() {
  // ...
  m2.draw();
  // ...
}

In order to work with the library, please include "M2tk.h". The line

M2_LABEL(hello_world_label, NULL, "Hello World");

defines an element which is later displayed and shown to the user. M2_LABEL is a simple read-only element. The first argument for M2_LABEL defines the name (hello_world_label) of the element. The text (third argument) assigned to M2_LABEL will appear on the output device. Elements could be nested, but in this example, the single element M2_LABEL already defindes the complete element tree. So, the element hello_world_label is also the root element and will be assigned to the m2tklib (first argument of the constructor):

M2tk m2(&hello_world_label, NULL, NULL, m2_gh_u8g_bfs);

As usual within the Arduino Environment, there is a class M2tk, which defines the access to the m2tklib. In this example m2 is defined as an object for this class.

Note: It is not allowed to define more than one M2tk object.

The constructor for m2 accepts several arguments, two of them are important for this example:

• First argument: The root element of the element tree.
• Last argument: The graphics handler (a procedure called m2_gh_u8g_bfs) for the output device (U8g library)

A graphics handler not only defines the output devices itself. A graphics handler is also responsible how elements are rendered and displayed on the LCD. The graphics handler sometimes require additional steps. For example the U8g handler also requires to know which font to use (see setup() procedure in the following example).

Finally U8glib and M2tklib need to be connected. This is done with the m2_SetU8g procedure (unfortunately, this is not a member function of the m2 object). The second argument defines the style for radio and toggle icons.

#include "U8glib.h"
#include "M2tk.h"
#include "m2ghu8g.h"

U8GLIB_DOGM128 u8g(13, 11, 10, 9);                                      // Setup U8glib with DOGM128 display: SPI Com: SCK = 13, MOSI = 11, CS = 10, A0 = 9

M2_LABEL(hello_world_label, NULL, "Hello World");
M2tk m2(&hello_world_label, NULL, NULL, m2_gh_u8g_bfs);

void draw(void) {
    m2.draw();
}

void setup() {
  /* connect u8glib with m2tklib */
  m2_SetU8g(u8g.getU8g(), m2_u8g_box_icon);

  /* assign u8g font to index 0 */
  m2.setFont(0, u8g_font_7x13);
}

void loop() {
  u8g.firstPage();  
  do {
    draw();
  } while( u8g.nextPage() );
}

Result (128x64 display):

Conclusion

• There can be only one object of class M2tk. This means, that only one output device is allowed.
• The content of the display is build by a hierarchical structure of elements.
• Any references to elements must use the adress operator &.
• Each output device has a special callback procedure.

Links

• Next Tutorial: Tutorial 2: User Input
• Wiki Start Page