Merge pull request #5549 from basilfx/feature/pkg_u8g2

pkg: u8g2: add graphics library
7 years ago · 6d9c9279f0
parent da1e364ef6 7033401eaa
commit 6d9c9279f0
8 changed files with 705 additions and 0 deletions
--- a/pkg/u8g2/Makefile
+++ b/pkg/u8g2/Makefile
@ -0,0 +1,10 @@
+PKG_NAME=u8g2
+PKG_URL=https://github.com/olikraus/u8g2
+PKG_VERSION=4c7ecf099e766b9c678d3453d6b932c8290bdb6b
+
+.PHONY: all
+
+all: git-download
+	"$(MAKE)" -C $(PKG_BUILDDIR)
+
+include $(RIOTBASE)/pkg/pkg.mk
--- a/pkg/u8g2/Makefile.include
+++ b/pkg/u8g2/Makefile.include
@ -0,0 +1,6 @@
+INCLUDES += -I$(BINDIRBASE)/pkg/$(BOARD)/u8g2/csrc
+
+# Link SDL if enabled.
+ifneq (,$(filter u8g2_sdl,$(USEMODULE)))
+  LINKFLAGS += `sdl-config --libs`
+endif
--- a/pkg/u8g2/README.md
+++ b/pkg/u8g2/README.md
@ -0,0 +1,63 @@
+# U8g2
+
+## Introduction
+[U8g2](https://github.com/olikraus/u8g2) is a monochrome graphics library for LCDs and OLEDs. It contains both drivers and high-level drawing routines.
+
+The library is originally written for Arduino boards, but it runs just fine on other platforms, as long as the right drivers are available.
+
+## Usage
+Just put `USEPKG += u8g2` in your Makefile and `#include "u8g2.h"` to your code. Refer to the [U8g2 wiki](https://github.com/olikraus/u8g2/wiki) for more information on the API.
+
+## RIOT-OS interface
+This package patches the original source to add an interface for RIOT-OS.
+
+The following two callbacks add support for the included drivers via I2C and SPI peripherals:
+
+* `u8x8_byte_riotos_hw_spi`
+* `u8x8_byte_riotos_hw_i2c`
+
+For timing and GPIO related operations, the following callback is available.
+
+* `u8x8_gpio_and_delay_riotos`
+
+U8g2 needs to map pin numbers to RIOT-OS pin numbers. It also needs to know which peripheral to use. The following two methods can be used to set this information.
+
+* `u8g2_SetPins(u8g2_dev, pins, bitmap)`
+* `u8g2_SetDevice(u8g2_dev, dev)`
+
+Note: `pins` should point to `gpio_t` array of U8g2 pin numbers to RIOT-OS pins. Due to this, `pins` can take up an additional 100 bytes, because it will use memory for the pins you do not map. You can overcome this limitation by implementing `u8x8_gpio_and_delay_riotos` yourself and hardcode the pins.
+
+### Example
+```
+u8g2_t u8g2;
+
+gpio_t pins[] = {
+    [U8X8_PIN_CS] = GPIO(PA, 0),
+    [U8X8_PIN_DC] = GPIO(PA, 1),
+    [U8X8_PIN_RESET] = GPIO(PA, 2)
+};
+
+uint32_t bitmap = (
+    (1 << U8X8_PIN_CS) +
+    (1 << U8X8_PIN_DC) +
+    (1 << U8X8_PIN_RESET)
+);
+
+u8g2_Setup_ssd1306_128x64_noname_1(&u8g2, U8G2_R0, u8x8_byte_riotos_hw_spi, u8x8_gpio_and_delay_riotos);
+
+u8g2_SetPins(&u8g2, pins, bitmap);
+u8g2_SetDevice(&u8g2, SPI_0);
+```
+
+## Virtual displays
+For targets without an I2C or SPI, virtual displays are available. These displays are part of U8g2, but are not compiled by default.
+
+* By adding `USEMODULE += u8g2_utf8`, a terminal display is used as virtual display, using UTF8 block characters that are printed to stdout.
+* By adding `USEMODULE += u8g2_sdl`, a SDL virtual display will be used. This is only available on native targets that have SDL installed. It uses `sdl-config` to find the headers and libraries. Note that RIOT-OS builds 32-bit binaries and requires 32-bit SDL libraries.
+
+### Example
+```
+u8g2_t u8g2;
+
+u8g2_SetupBuffer_Utf8(&u8g2, U8G2_R0);
+```
--- a/pkg/u8g2/patches/0001-u8g2-add-riot-os-makefiles.patch
+++ b/pkg/u8g2/patches/0001-u8g2-add-riot-os-makefiles.patch
@ -0,0 +1,76 @@
+From 09dad731ec608609836aae37ab32fbceec8f3eaa Mon Sep 17 00:00:00 2001
+From: Bas Stottelaar <basstottelaar@gmail.com>
+Date: Tue, 24 May 2016 20:17:39 +0200
+Subject: [PATCH 1/2] u8g2: add riot-os makefiles.
+
+---
+ Makefile                 | 22 ++++++++++++++++++++++
+ csrc/Makefile            |  3 +++
+ sys/sdl/common/Makefile  |  5 +++++
+ sys/utf8/common/Makefile |  3 +++
+ 4 files changed, 33 insertions(+)
+ create mode 100644 Makefile
+ create mode 100644 csrc/Makefile
+ create mode 100644 sys/sdl/common/Makefile
+ create mode 100644 sys/utf8/common/Makefile
+
+diff --git a/Makefile b/Makefile
+new file mode 100644
+index 0000000..ec64fab
+--- /dev/null
+++ b/Makefile
+@@ -0,0 +1,22 @@
+DIRS += csrc
+
+# SDL can be used as a virtual display, but is for native target only.
+ifneq (,$(filter u8g2_sdl,$(USEMODULE)))
+  DIRS += sys/sdl/common
+endif
+
+# UTF8 virtual display is not part of core. Therefore it is a separate module.
+ifneq (,$(filter u8g2_utf8,$(USEMODULE)))
+  DIRS += sys/utf8/common
+endif
+
+# Compiling U8g2 will generate a lot of compiler warnings, which are treated
+# as errors. For the sake of simplicity, ignore them.
+CFLAGS += -Wno-empty-translation-unit \
+          -Wno-newline-eof \
+          -Wno-unused-parameter \
+          -Wno-unused \
+          -Wno-overlength-strings \
+          -Wno-pointer-arith
+
+include $(RIOTBASE)/Makefile.base
+diff --git a/csrc/Makefile b/csrc/Makefile
+new file mode 100644
+index 0000000..1023a87
+--- /dev/null
+++ b/csrc/Makefile
+@@ -0,0 +1,3 @@
+MODULE = u8g2
+
+include $(RIOTBASE)/Makefile.base
+diff --git a/sys/sdl/common/Makefile b/sys/sdl/common/Makefile
+new file mode 100644
+index 0000000..ce8b90b
+--- /dev/null
+++ b/sys/sdl/common/Makefile
+@@ -0,0 +1,5 @@
+MODULE = u8g2_sdl
+
+CFLAGS += `sdl-config --cflags`
+
+include $(RIOTBASE)/Makefile.base
+diff --git a/sys/utf8/common/Makefile b/sys/utf8/common/Makefile
+new file mode 100644
+index 0000000..32e7913
+--- /dev/null
+++ b/sys/utf8/common/Makefile
+@@ -0,0 +1,3 @@
+MODULE = u8g2_utf8
+
+include $(RIOTBASE)/Makefile.base
+-- 
+2.8.1
+
--- a/pkg/u8g2/patches/0002-u8g2-add-riot-os-interface.patch
+++ b/pkg/u8g2/patches/0002-u8g2-add-riot-os-interface.patch
@ -0,0 +1,257 @@
+From e6838299ea324752a559ce1a583c7e2259a121b8 Mon Sep 17 00:00:00 2001
+From: Bas Stottelaar <basstottelaar@gmail.com>
+Date: Wed, 22 Jun 2016 18:04:31 +0200
+Subject: [PATCH 2/2] u8g2: add riot-os interface.
+
+---
+ csrc/u8g2.h        |   4 +-
+ csrc/u8g2_riotos.c | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++
+ csrc/u8x8.h        |  17 +++++-
+ 3 files changed, 178 insertions(+), 4 deletions(-)
+ create mode 100644 csrc/u8g2_riotos.c
+
+diff --git a/csrc/u8g2.h b/csrc/u8g2.h
+index 32a9570..c8cc1de 100644
+--- a/csrc/u8g2.h
+++ b/csrc/u8g2.h
+@@ -343,6 +343,9 @@ struct u8g2_struct
+ #define u8g2_SetMenuDownPin(u8g2, val) u8x8_SetMenuDownPin(u8g2_GetU8x8(u8g2), (val))
+ #endif
+ 
+#define u8g2_SetPins(u8x8,pins,pins_enabled) u8x8_SetPins(u8g2_GetU8x8(&u8g2), pins, pins_enabled)
+#define u8g2_SetDevice(u8x8,device) u8x8_SetDevice(u8g2_GetU8x8(&u8g2), device)
+
+ /*==========================================*/
+ /* u8g2_setup.c */
+ 
+@@ -1441,4 +1444,3 @@ extern const uint8_t u8g2_font_pcsenior_8u[] U8G2_FONT_SECTION("u8g2_font_pcseni
+ 
+ 
+ #endif
+-
+diff --git a/csrc/u8g2_riotos.c b/csrc/u8g2_riotos.c
+new file mode 100644
+index 0000000..4b0f896
+--- /dev/null
+++ b/csrc/u8g2_riotos.c
+@@ -0,0 +1,161 @@
+#include "u8g2.h"
+
+#include "xtimer.h"
+
+#include "periph/spi.h"
+#include "periph/i2c.h"
+#include "periph/gpio.h"
+
+#include <stdio.h>
+
+#if SPI_NUMOF
+static spi_speed_t u8x8_pulse_width_to_spi_speed(uint32_t pulse_width)
+{
+    uint32_t cycle_time = 2 * pulse_width;
+
+    if (cycle_time < 100) {
+        return SPI_SPEED_10MHZ;
+    } else if (cycle_time < 200) {
+        return SPI_SPEED_5MHZ;
+    } else if (cycle_time < 1000) {
+        return SPI_SPEED_1MHZ;
+    } else if (cycle_time < 2500) {
+        return SPI_SPEED_400KHZ;
+    }
+
+    return SPI_SPEED_100KHZ;
+}
+#endif /* SPI_NUMOF */
+
+#if SPI_NUMOF
+static spi_speed_t u8x8_takeover_edge_to_spi_conf(uint32_t takeover_edge)
+{
+    if (takeover_edge == 2) {
+        return SPI_CONF_SECOND_RISING;
+    }
+
+    return SPI_CONF_FIRST_FALLING;
+}
+#endif /* SPI_NUMOF */
+
+static void u8x8_enable_pins(gpio_t* pins, uint32_t pins_enabled)
+{
+    uint8_t i;
+
+    for (i = 0; i < 32; i++) {
+        if (pins_enabled & (1 << i)) {
+            if (pins[i] != GPIO_UNDEF) {
+                if (i < U8X8_PIN_OUTPUT_CNT) {
+                    gpio_init(pins[i], GPIO_OUT);
+                } else {
+                    gpio_init(pins[i], GPIO_IN);
+                }
+            }
+        }
+    }
+}
+
+uint8_t u8x8_gpio_and_delay_riotos(u8x8_t *u8g2, uint8_t msg, uint8_t arg_int, void *arg_ptr)
+{
+    (void) arg_ptr;
+
+    switch (msg) {
+        case U8X8_MSG_GPIO_AND_DELAY_INIT:
+            u8x8_enable_pins(u8g2->pins, u8g2->pins_enabled);
+            break;
+        case U8X8_MSG_DELAY_MILLI:
+            xtimer_usleep(arg_int * 1000);
+            break;
+        case U8X8_MSG_DELAY_10MICRO:
+            xtimer_usleep(10);
+            break;
+        case U8X8_MSG_DELAY_100NANO:
+            xtimer_nanosleep(100);
+            break;
+        case U8X8_MSG_GPIO_CS:
+            gpio_write(u8g2->pins[U8X8_PIN_CS], arg_int);
+            break;
+        case U8X8_MSG_GPIO_DC:
+            gpio_write(u8g2->pins[U8X8_PIN_DC], arg_int);
+            break;
+        case U8X8_MSG_GPIO_RESET:
+            gpio_write(u8g2->pins[U8X8_PIN_RESET], arg_int);
+            break;
+        default:
+            return 0;
+    }
+
+    return 1;
+}
+
+#if SPI_NUMOF
+uint8_t u8x8_byte_riotos_hw_spi(u8x8_t *u8g2, uint8_t msg, uint8_t arg_int, void *arg_ptr)
+{
+    spi_t dev = (spi_t) u8g2->dev;
+
+    switch (msg) {
+        case U8X8_MSG_BYTE_SEND:
+            spi_transfer_bytes(dev, (char *) arg_ptr, NULL, arg_int);
+            break;
+        case U8X8_MSG_BYTE_INIT:
+            spi_init_master(dev,
+                            u8x8_takeover_edge_to_spi_conf(u8g2->display_info->sck_takeover_edge),
+                            u8x8_pulse_width_to_spi_speed(u8g2->display_info->sck_pulse_width_ns));
+            break;
+        case U8X8_MSG_BYTE_SET_DC:
+            u8x8_gpio_SetDC(u8g2, arg_int);
+            break;
+        case U8X8_MSG_BYTE_START_TRANSFER:
+            spi_acquire(dev);
+
+            u8x8_gpio_SetCS(u8g2, u8g2->display_info->chip_enable_level);
+            u8g2->gpio_and_delay_cb(u8g2, U8X8_MSG_DELAY_NANO, u8g2->display_info->post_chip_enable_wait_ns, NULL);
+            break;
+        case U8X8_MSG_BYTE_END_TRANSFER:
+            u8g2->gpio_and_delay_cb(u8g2, U8X8_MSG_DELAY_NANO, u8g2->display_info->pre_chip_disable_wait_ns, NULL);
+            u8x8_gpio_SetCS(u8g2, u8g2->display_info->chip_disable_level);
+
+            spi_release(dev);
+            break;
+        default:
+            return 0;
+    }
+
+    return 1;
+}
+#endif /* SPI_NUMOF */
+
+#if I2C_NUMOF
+uint8_t u8x8_byte_riotos_hw_i2c(u8x8_t *u8g2, uint8_t msg, uint8_t arg_int, void *arg_ptr)
+{
+    static uint8_t buffer[255];
+    static uint8_t index;
+
+    i2c_t dev = (i2c_t) u8g2->dev;
+
+    switch (msg) {
+        case U8X8_MSG_BYTE_SEND:
+            while (arg_int--) {
+                buffer[index++] = *((uint8_t *)arg_ptr++);
+            }
+            break;
+        case U8X8_MSG_BYTE_INIT:
+            i2c_init_master(dev, I2C_SPEED_FAST);
+            break;
+        case U8X8_MSG_BYTE_SET_DC:
+            break;
+        case U8X8_MSG_BYTE_START_TRANSFER:
+            i2c_acquire(dev);
+            index = 0;
+            break;
+        case U8X8_MSG_BYTE_END_TRANSFER:
+            i2c_write_bytes(dev, u8x8_GetI2CAddress(u8g2), (char *) buffer, index);
+            i2c_release(dev);
+            break;
+        default:
+            return 0;
+    }
+
+    return 1;
+}
+#endif /* I2C_NUMOF */
+diff --git a/csrc/u8x8.h b/csrc/u8x8.h
+index 13050f6..36eeab0 100644
+--- a/csrc/u8x8.h
+++ b/csrc/u8x8.h
+@@ -107,6 +107,8 @@
+ #include <stdint.h>
+ #include <stddef.h>
+ 
+#include "periph/gpio.h"
+
+ #if defined(__GNUC__) && defined(__AVR__)
+ #include <avr/pgmspace.h>
+ #endif 
+@@ -154,9 +156,9 @@ extern "C" {
+ #  define u8x8_pgm_read(adr) (*(const uint8_t *)(adr)) 
+ #endif
+ 
+-#ifdef ARDUINO
+-#define U8X8_USE_PINS
+-#endif
+//#ifdef ARDUINO
+//#define U8X8_USE_PINS
+//#endif
+ 
+ /*==========================================*/
+ /* U8X8 typedefs and data structures */
+@@ -308,6 +310,10 @@ struct u8x8_struct
+ #ifdef U8X8_USE_PINS 
+   uint8_t pins[U8X8_PIN_CNT];	/* defines a pinlist: Mainly a list of pins for the Arduino Envionment, use U8X8_PIN_xxx to access */
+ #endif
+
+  gpio_t* pins;
+  uint32_t pins_enabled;
+  uint32_t dev;
+ };
+ 
+ #define u8x8_GetCols(u8x8) ((u8x8)->display_info->tile_width)
+@@ -327,6 +333,8 @@ struct u8x8_struct
+ #define u8x8_SetMenuDownPin(u8x8, val) u8x8_SetPin((u8x8),U8X8_PIN_MENU_DOWN,(val))
+ #endif
+ 
+#define u8x8_SetPins(u8x8,pins,pins_enabled) {(u8x8)->pins = (pins); (u8x8)->pins_enabled = (pins_enabled);}
+#define u8x8_SetDevice(u8x8,device) ((u8x8)->dev = device)
+ 
+ /*==========================================*/
+ 
+@@ -781,6 +789,9 @@ extern const uint8_t u8x8_font_pcsenior_u[] U8X8_FONT_SECTION("u8x8_font_pcsenio
+ 
+ /* end font list */
+ 
+extern uint8_t u8x8_byte_riotos_hw_spi(u8x8_t *u8g2, uint8_t msg, uint8_t arg_int, void *arg_ptr);
+extern uint8_t u8x8_gpio_and_delay_riotos(u8x8_t *u8g2, uint8_t msg, uint8_t arg_int, void *arg_ptr);
+extern uint8_t u8x8_byte_riotos_hw_i2c(u8x8_t *u8g2, uint8_t msg, uint8_t arg_int, void *arg_ptr);
+ 
+ #ifdef __cplusplus
+ }
+-- 
+2.8.1
+
--- a/tests/pkg_u8g2/Makefile
+++ b/tests/pkg_u8g2/Makefile
@ -0,0 +1,54 @@
+APPLICATION = pkg_u8g2
+include ../Makefile.tests_common
+
+# These boards have not sufficient memory
+BOARD_BLACKLIST += chronos msb-430 msb-430h telosb wsn430-v1_3b wsn430-v1_4 z1
+
+USEMODULE += xtimer
+
+USEPKG += u8g2
+
+# set default device parameters in case they are undefined
+TEST_U8G2_OUTPUT    ?= 1
+TEST_U8G2_DISPLAY   ?= u8g2_Setup_ssd1306_128x64_noname_1
+
+TEST_U8G2_I2C       ?= 0
+TEST_U8G2_SPI       ?= 0
+
+TEST_U8G2_ADDR      ?= 0x78
+
+TEST_U8G2_PIN_CS    ?= GPIO_PIN\(0,0\)
+TEST_U8G2_PIN_DC    ?= GPIO_PIN\(0,0\)
+TEST_U8G2_PIN_RESET ?= GPIO_PIN\(0,0\)
+
+# features depend on output type
+ifeq ($(TEST_U8G2_OUTPUT),1)
+USEMODULE += u8g2_utf8
+endif
+
+ifeq ($(TEST_U8G2_OUTPUT),2)
+USEMODULE += u8g2_sdl
+endif
+
+ifeq ($(TEST_U8G2_OUTPUT),3)
+FEATURES_REQUIRED += periph_gpio periph_spi
+endif
+
+ifeq ($(TEST_U8G2_OUTPUT),4)
+FEATURES_REQUIRED += periph_gpio periph_i2c
+endif
+
+# export parameters
+CFLAGS += -DTEST_U8G2_OUTPUT=$(TEST_U8G2_OUTPUT)
+CFLAGS += -DTEST_U8G2_DISPLAY=$(TEST_U8G2_DISPLAY)
+
+CFLAGS += -DTEST_U8G2_SPI=$(TEST_U8G2_SPI)
+CFLAGS += -DTEST_U8G2_I2C=$(TEST_U8G2_I2C)
+
+CFLAGS += -DTEST_U8G2_ADDR=$(TEST_U8G2_ADDR)
+
+CFLAGS += -DTEST_U8G2_PIN_CS=$(TEST_U8G2_PIN_CS)
+CFLAGS += -DTEST_U8G2_PIN_DC=$(TEST_U8G2_PIN_DC)
+CFLAGS += -DTEST_U8G2_PIN_RESET=$(TEST_U8G2_PIN_RESET)
+
+include $(RIOTBASE)/Makefile.include
--- a/tests/pkg_u8g2/README.md
+++ b/tests/pkg_u8g2/README.md
@ -0,0 +1,44 @@
+# U8g2 Package Test
+
+## About
+This is a test application for the U8g2 package. This package is a graphical display library, including display drivers.
+
+## Usage
+This test application will initialize the U8g2 to output on one of the following:
+
+* output to terminal virtual screen.
+* output to SDL virtual screen.
+* output to I2C graphics screen.
+* output to SPI graphics screen.
+
+Note: you may have to run `make clean` between different output modes.
+
+### Output to terminal
+To output to this virtual screen, supply `TEST_U8G2_OUTPUT=1` to the `make` command.
+
+### Output to SDL
+To output to this virtual screen, supply `TEST_U8G2_OUTPUT=2` to the `make` command.
+
+This is a native-only option and requires SDL (32-bits) to be installed.
+
+### Output to SPI
+To output to screen, supply `TEST_U8G2_OUTPUT=3` to the `make` command.
+
+* `TEST_U8G2_SPI` &mdash; The SPI device.
+* `TEST_U8G2_PIN_CS` &mdash; If applicable, the CS pin.
+* `TEST_U8G2_PIN_DC` &mdash; If applicable, the Command/Data pin.
+* `TEST_U8G2_PIN_RESET` &mdash; If applicable, the reset pin.
+* `TEST_U8G2_DISPLAY` &mdash; The used display driver (see https://github.com/olikraus/u8g2/wiki/u8g2setupc). Make sure you select a SPI compatible display.
+
+### Output to I2C
+To output to screen, supply `TEST_U8G2_OUTPUT=4` to the `make` command.
+
+Furthermore, you can configure the following:
+
+* `TEST_U8G2_I2C` &mdash; The I2C device.
+* `TEST_U8G2_ADDR` &mdash; The address to write commands to.
+* `TEST_U8G2_PIN_RESET` &mdash; If applicable, the reset pin.
+* `TEST_U8G2_DISPLAY` &mdash; The used display driver (see https://github.com/olikraus/u8g2/wiki/u8g2setupc). Make sure you select an I2C compatible display.
+
+## Expected result
+The output of this test depends on the output mode and used hardware. If it works, the application cycles through three screens with the text: 'This is RIOT-OS'.
--- a/tests/pkg_u8g2/main.c
+++ b/tests/pkg_u8g2/main.c
@ -0,0 +1,195 @@
+/*
+ * Copyright (C) 2016 Bas Stottelaar <basstottelaar@gmail.com>
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     tests
+ * @{
+ *
+ * @file
+ * @brief       Test application for the U8g2 package.
+ *
+ * @author      Bas Stottelaar <basstottelaar@gmail.com>
+ *
+ * @}
+ */
+
+#define TEST_U8G2_OUTPUT_STDOUT 1
+#define TEST_U8G2_OUTPUT_SDL 2
+#define TEST_U8G2_OUTPUT_SPI 3
+#define TEST_U8G2_OUTPUT_I2C 4
+
+#ifndef TEST_U8G2_OUTPUT
+#error "TEST_U8G2_OUTPUT not defined"
+#endif
+#ifndef TEST_U8G2_DISPLAY
+#error "TEST_U8G2_DISPLAY not defined"
+#endif
+
+#if TEST_U8G2_OUTPUT == TEST_U8G2_OUTPUT_I2C
+#ifndef TEST_U8G2_I2C
+#error "TEST_U8G2_I2C not defined"
+#endif
+#ifndef TEST_U8G2_ADDR
+#error "TEST_U8G2_ADDR not defined"
+#endif
+#ifndef TEST_U8G2_PIN_RESET
+#error "TEST_U8G2_PIN_RESET not defined"
+#endif
+#endif
+
+#if TEST_U8G2_OUTPUT == TEST_U8G2_OUTPUT_SPI
+#ifndef TEST_U8G2_SPI
+#error "TEST_U8G2_SPI not defined"
+#endif
+#ifndef TEST_U8G2_PIN_CS
+#error "TEST_U8G2_PIN_CS not defined"
+#endif
+#ifndef TEST_U8G2_PIN_DC
+#error "TEST_U8G2_PIN_DC not defined"
+#endif
+#ifndef TEST_U8G2_PIN_RESET
+#error "TEST_U8G2_PIN_RESET not defined"
+#endif
+#endif
+
+#include <stdio.h>
+
+#include "periph/gpio.h"
+
+#include "xtimer.h"
+#include "u8g2.h"
+
+/**
+ * @brief   RIOT-OS logo, 64x32 pixels at 8 pixels per byte.
+ */
+static const uint8_t logo[] = {
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0xE0,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0F, 0xF8, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x1F, 0xF8, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x3E, 0x3C,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x78, 0x1E, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x70, 0x0E, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x70, 0x0E,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x0E, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0xF0, 0x0E, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x1E,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3C, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0xF0, 0x7C, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x73, 0xF8,
+    0x30, 0x3C, 0x3F, 0xC0, 0x00, 0x0C, 0x77, 0xF0, 0x38, 0x7E, 0x3F, 0xC0,
+    0x00, 0x7E, 0x73, 0xC0, 0x38, 0xE7, 0x06, 0x00, 0x00, 0xFC, 0x71, 0x00,
+    0x38, 0xE3, 0x06, 0x00, 0x01, 0xF0, 0x70, 0x00, 0x38, 0xE3, 0x06, 0x00,
+    0x01, 0xC0, 0x70, 0x00, 0x38, 0xE3, 0x06, 0x00, 0x03, 0x80, 0x70, 0xC0,
+    0x38, 0xE3, 0x06, 0x00, 0x03, 0x80, 0x71, 0xE0, 0x38, 0xE3, 0x06, 0x00,
+    0x03, 0x80, 0x70, 0xE0, 0x38, 0xE3, 0x06, 0x00, 0x03, 0x80, 0x70, 0xF0,
+    0x38, 0xE3, 0x06, 0x00, 0x03, 0x80, 0x70, 0x70, 0x38, 0xE3, 0x06, 0x00,
+    0x03, 0x80, 0xF0, 0x78, 0x38, 0xE3, 0x06, 0x00, 0x03, 0xC1, 0xE0, 0x3C,
+    0x38, 0xE7, 0x06, 0x00, 0x01, 0xE3, 0xE0, 0x3C, 0x38, 0x7E, 0x06, 0x00,
+    0x01, 0xFF, 0xC0, 0x1C, 0x30, 0x3C, 0x06, 0x00, 0x00, 0x7F, 0x80, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x1C, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00
+};
+
+#if (TEST_U8G2_OUTPUT == TEST_U8G2_OUTPUT_I2C) || (TEST_U8G2_OUTPUT == TEST_U8G2_OUTPUT_SPI)
+/**
+ * @brief   RIOT-OS pin maping of U8g2 pin numbers to RIOT-OS GPIO pins.
+ * @note    To minimize the overhead, you can implement an alternative for
+ *          u8x8_gpio_and_delay_riotos.
+ */
+static gpio_t pins[] = {
+    [U8X8_PIN_CS] = TEST_U8G2_PIN_CS,
+    [U8X8_PIN_DC] = TEST_U8G2_PIN_DC,
+    [U8X8_PIN_RESET] = TEST_U8G2_PIN_RESET
+};
+
+/**
+ * @brief   Bit mapping to indicate which pins are set.
+ */
+static uint32_t pins_enabled = (
+    (1 << U8X8_PIN_CS) +
+    (1 << U8X8_PIN_DC) +
+    (1 << U8X8_PIN_RESET)
+);
+#endif
+
+int main(void)
+{
+    uint32_t screen = 0;
+    u8g2_t u8g2;
+
+    /* initialize to stdout */
+#if TEST_U8G2_OUTPUT == TEST_U8G2_OUTPUT_STDOUT
+    puts("initializing to stdout.");
+
+    u8g2_SetupBuffer_Utf8(&u8g2, U8G2_R0);
+#endif
+
+    /* initialize to virtual SDL (native only) */
+#if TEST_U8G2_OUTPUT == TEST_U8G2_OUTPUT_SDL
+    puts("initializing to SDL.");
+
+    u8g2_SetupBuffer_SDL_128x64_4(&u8g2, U8G2_R0);
+#endif
+
+    /* initialize to SPI */
+#if TEST_U8G2_OUTPUT == TEST_U8G2_OUTPUT_SPI
+    puts("initializing to SPI.");
+
+    TEST_U8G2_DISPLAY(&u8g2, U8G2_R0, u8x8_byte_riotos_hw_spi, u8x8_gpio_and_delay_riotos);
+
+    u8g2_SetPins(&u8g2, pins, pins_enabled);
+    u8g2_SetDevice(&u8g2, TEST_U8G2_SPI);
+#endif
+
+    /* initialize to I2C */
+#if TEST_U8G2_OUTPUT == TEST_U8G2_OUTPUT_I2C
+    puts("initializing to I2C.");
+
+    TEST_U8G2_DISPLAY(&u8g2, U8G2_R0, u8x8_byte_riotos_hw_i2c, u8x8_gpio_and_delay_riotos);
+
+    u8g2_SetPins(&u8g2, pins, pins_enabled);
+    u8g2_SetDevice(&u8g2, TEST_U8G2_I2C);
+    u8g2_SetI2CAddress(&u8g2, TEST_U8G2_ADDR);
+#endif
+
+    /* initialize the display */
+    puts("Initializing display.");
+
+    u8g2_InitDisplay(&u8g2);
+    u8g2_SetPowerSave(&u8g2, 0);
+
+    /* start drawing in a loop */
+    puts("Drawing on screen.");
+
+    while (true) {
+        u8g2_FirstPage(&u8g2);
+
+        do {
+            u8g2_SetDrawColor(&u8g2, 1);
+            u8g2_SetFont(&u8g2, u8g2_font_helvB12_tf);
+
+            if (screen == 0) {
+                u8g2_DrawStr(&u8g2, 12, 22, "THIS");
+            } else if (screen == 1) {
+                u8g2_DrawStr(&u8g2, 24, 22, "IS");
+            } else if (screen == 2) {
+                u8g2_DrawBitmap(&u8g2, 0, 0, 8, 32, logo);
+            }
+        } while (u8g2_NextPage(&u8g2));
+
+#if TEST_U8G2_OUTPUT == TEST_U8G2_OUTPUT_STDOUT
+        /* transfer screen buffer to stdout */
+        utf8_show();
+#endif
+
+        /* show screen in next iteration */
+        screen = (screen + 1) % 3;
+
+        /* sleep a little */
+        xtimer_sleep(1);
+    }
+
+    return 0;
+}