u8logreference

Introduction to U8log

U8log is an extension to U8g2 and U8x8. It implements a text window with automatic vertical scrolling. Text is written to the current cursor position within the text window. The cursor position is modified by special character commands:

Char	Decimal	Description
`\n`	10	Goto first position of the next line.
`\r`	13	Goto first position of the same line.
`\t`	9	Jump to the next tab position.
`\f`	12	Clear the screen and goto upper left corner.

U8log can be used for:

Output of boot/startup information
Error logging
Debugging
Output of sensor values

Features:

Vertical scolling
All features of Arduino Serial.print are supported
Automatic or manual display update

Implementation:

class U8G2LOG for U8g2
class U8X8LOG for U8x8
u8x8_t struct with plain c API

Examples

U8x8 with Automatic Display Update

For the automatic display update, connect the U8x8log object with the U8x8 object. No further access to U8x8 is required. Just print data to U8x8log. Refresh of the screen is handled by U8x8log automatically.

Steps are:

Create U8x8 object
Create U8x8log object
Setup static memory for the text window
U8x8.begin()
U8x8log.begin(): This will connect to U8x8 and assign the static memory
Use U8x8log to print to the display

The size of the static memory depends on the number of chars which may fit on the display. For U8x8 just devide the display width and height by 8 to get the corresponding width and height for the text window.

// U8x8 constructor for your display
U8X8_SSD1306_128X64_NONAME_4W_HW_SPI u8x8(/* cs=*/ 10, /* dc=*/ 9, /* reset=*/ 8);

// Create a U8x8log object
U8X8LOG u8x8log;


// Define the dimension of the U8x8log window
#define U8LOG_WIDTH 16
#define U8LOG_HEIGHT 8

// Allocate static memory for the U8x8log window
uint8_t u8log_buffer[U8LOG_WIDTH*U8LOG_HEIGHT];

void setup(void)
{
  // Startup U8x8
  u8x8.begin();
  
  // Set a suitable font. This font will be used for U8x8log
  u8x8.setFont(u8x8_font_chroma48medium8_r);
  
  // Start U8x8log, connect to U8x8, set the dimension and assign the static memory
  u8x8log.begin(u8x8, U8LOG_WIDTH, U8LOG_HEIGHT, u8log_buffer);
  
  // Set the U8x8log redraw mode
  u8x8log.setRedrawMode(1);		// 0: Update screen with newline, 1: Update screen for every char  
}

void loop(void) {
  // Print a number on the U8x8log window
  // The display will be refreshed
  u8x8log.print(millis());
  // Print a new line, scroll the text window content if required
  // Refresh the screen
  u8x8log.print("\n");
  
  delay(500);
}

This example is available as .ino file here.

U8g2 with Automatic Display Update

This is almost identical to the previous example: Connect the U8g2log object with the U8g2 object. No further access to U8g2 is required. Just print data to U8g2log. Refresh of the screen is handled by U8g2log automatically.

Steps are:

Create U8g2 object
Create U8g2log object
Setup static memory for the text window
U8g2.begin()
U8g2log.begin(): This will connect to U8g2 and assign the static memory
Use U8g2log to print to the display

The size of the static memory depends on the number of chars which may fit on the display and the font, which is used for the chars. To simplify the calculation, it is suggested to use monospaced fonts only. A list of monospaced fonts is available here.

Example:

Assume 128x64 OLED display and font u8g2_font_tom_thumb_4x6_mf
Chars in the font u8g2_font_tom_thumb_4x6_mf all have a height of 6 and width of 4 pixel.
Width for the text window: 128 / 4 = 32 chars
Height for the text window: 64 / 6 = 10 chars

// U8g2 constructor
U8G2_SSD1306_128X64_NONAME_1_4W_HW_SPI u8g2(U8G2_R0, /* cs=*/ 10, /* dc=*/ 9, /* reset=*/ 8);

// Create a U8g2log object
U8G2LOG u8g2log;

// assume 4x6 font, define width and height
#define U8LOG_WIDTH 32
#define U8LOG_HEIGHT 10

// allocate memory
uint8_t u8log_buffer[U8LOG_WIDTH*U8LOG_HEIGHT];

void setup(void) {
  u8g2.begin();    
  u8g2.setFont(u8g2_font_tom_thumb_4x6_mf);	// set the font for the terminal window
  u8g2log.begin(u8g2, U8LOG_WIDTH, U8LOG_HEIGHT, u8log_buffer);	// connect to u8g2, assign buffer
  u8g2log.setLineHeightOffset(0);	// set extra space between lines in pixel, this can be negative
  u8g2log.setRedrawMode(0);		// 0: Update screen with newline, 1: Update screen for every char  
}

void loop(void) {
  // Print a number on the U8g2log window
  u8g2log.print(millis());
  // Print a new line, scroll the text window content if required
  // Refresh the screen
  u8g2log.print("\n");
  
  delay(500);
}

For U8g2 it is better to keep u8g2log.setRedrawMode(0) at the default value 0, which refreshes the display only with a newline char.

This example is available as .ino file here.

U8g2 Minimal Exampe with Automatic Display Update

Without further description, this is just a minimal U8g2 example:

U8G2_SSD1306_128X64_NONAME_1_4W_HW_SPI u8g2(U8G2_R0, /* cs=*/ 10, /* dc=*/ 9, /* reset=*/ 8);
U8G2LOG u8g2log;
uint8_t u8log_buffer[32*10];

void setup(void) {
  u8g2.begin();    
  u8g2.setFont(u8g2_font_tom_thumb_4x6_mf);	// set the font for the terminal window
  u8g2log.begin(u8g2, 32, 10, u8log_buffer);		// connect to u8g2, assign buffer
}

void loop(void) {
  u8g2log.print(millis());
  u8g2log.print("\n");
  
  delay(500);
}