In this guide we show how to use the U8G2 library to renderer menu items to an OLED unit with tcMenu. This rendering driver for U8G2 is built into the core menu designer download, meaning it’s available out of the box.
The U8G2 library supports a lot of different displays, with very different capabilities. This plugin concentrates on monochrome displays, mainly OLED that are supported by this library. It’s worth reading this guide fully so that you understand how we manage the various capabilities.
Before proceeding, you’ll need to make sure you’ve installed the U8G2 library (usually through library manager). Also, I’d recommend taking a read through the U8G2 library documentation if you’re not familiar with the library already. We’ll also assume you’ve got a menu structure already prepared in the menu designer UI.
Related documentation:
First, ensure your menu structure is saved and then choose Code -> Generate Code from the menu. Once the code generation dialog appears, you can change the display renderer by clicking on the image to the left of the renderer.
There are two possible ways to work with U8G2, firstly you can use the quick start option, where the code generator will create the display variable and set it up on your behalf. This is less configurable, but quicker for common cases. We’ll refer to this as “Quick Start”.
Alternatively, you can use the manual declared mode, where you manually declare the display variable and initialise the display yourself during setup, before the call to setupMenu
. We’ll refer to this as “Manual Configuration”.
When you use the quick start option, the code generator will create the display variable and initialise the display on your behalf. You will however be able to use the display in your own code, it will be exported using the variable name provided.
This is the name of the variable that the code generator will create on your behalf, it will also be export for you too in the projectName_menu.h file.
This is a choice from common U8G2 display types, if you’re not familiar with these, you may need to run one the U8G2 packaged examples to work out which option is right. Not all options are supported by quick start, but most common ones are. Should you need to use one of the unsupported cases, use the manual configuration option instead.
You can preconfigure the display rotation, using the regular U8G2 rotation constants. Where R0 is no rotation.
With this option selected, we replace the U8G2 data callback with one that calls yield every 16 bytes. In this case Wire
is used as the I2C communication method, and taskManager.yieldForMicros()
is called more frequently. This can make the application feel much faster with slower I2C.
For manually configured cases using the custom I2C plugin, you can also replace the data callback, we declare it in tcMenuU8g2.h
. The definition is:
uint8_t u8g2_byte_with_yield(u8x8_t *u8x8, uint8_t msg, uint8_t arg_int, void *arg_ptr);
When using any display type option that runs in software mode (contains SW in type) then the clock and data pins need to be provided, for either the software SPI or I2C pins. Be aware that software mode can be much slower than hardware mode, and you probably shouldn’t use it for larger SPI displays.
If you need to configure a reset pin for your display, set it here, or default to U8X8_PIN_NONE or -1.
Set these to the pins that will select the display (CS) and move between Register / Data selection. Only needed for SPI, set these to U8X8_PIN_NONE or -1 for I2C.
How many times the menu structure should be scanned for changes and redrawn if needed. TcMenu tries to minimise redraws where reasonably possible.
When you choose the manual configuration option, you need to create the display variable in your sketch, and make sure it is fully initialised before calling setupMenu
in your sketch.
As there are so many variations of display, you create the display variable in the sketch. This property is the name of the variable from your sketch. We’ll export it on your behalf so it can be used by the renderer.
This is the type of the graphics variable that you created. It must exactly match the variable type used for the display driver in your sketch.
How many times the menu structure should be scanned for changes and redrawn if needed. TcMenu tries to minimise redraws where reasonably possible.