Teensy

This page walks you through the process of setting up your Arduino environment to compile code that uses uGFX. It is assumed that you are familiar with the overall structure of the relevant arduino directories (sketches and libraries). There are four main steps to this:

1. install arduino and teensyduino
2. install uGFX in arduino's library directory
3. install the base uGFX-arduino libraries and drivers
4. write a project-specific config library (this has to be done for every project that uses uGFX in arduino)

Install arduino and teensyduino

1. Download and install arduino (https://www.arduino.cc/en/Main/Software). The instructions on this page have been tested with arduino 1.6.6
2. Doanload and install teensyduino (https://www.pjrc.com/teensy/td_download.html). The instructions on this page have been tested with teensyduino 1.26.

Install uGFX in arduino's library directory

Download uGFX (tested with repository state as of 2015-11-24 or later) and put it into arduino's library directory. You should end up with arduino libraries directory/ugfx/src and other files and folders.

uGFX can not be used as a stand-alone library, but must be wrapped with an arduino library that provides a suitable interface for the build process: one header and one source file, within the library's base directory. This is done by ugfx-arduino which is installed in the next step.

Install the base uGFX-arduino libraries and drivers

Download ugfx-arduino (https://github.com/crteensy/ugfx-arduino) and follow the steps included therein for installing the other sub-libraries:

1. put the main ugfx-arduino library into arduino's library directory. This arduino library wraps uGFX in such a way that arduino can compile it.
2. copy the libraries from ugfx-arduino/libraries into arduino's library directory as well. These are an example driver for the SSD1351 (ugfy-arduino-gdisp-ssd1351) and an example project-specific configuration library (example-ssd1351-ugfx-config).

Resulting arduino library directory structure after installation

After carrying out the steps outlined above, your arduino library directory should look like this:

libraries/
|- ugfx/
   |- ...
   |- src/
   |- ...
|- ugfx-arduino/
   |- ...
|- ugfx-arduino-gdisp-ssd1351/
   |- ...
|- example-ssd1351-ugfx-config/
   |- ...

If your directory structure looks like this, you can start (or restart) arduino and look for File -> Examples -> ugfx-arduino -> example-ssd1351-ugfx-config. If it is there, arduino has found the library and the example contained therein. It should now compile fine.

How to use ugfx-arduino in your own projects

For each project you create, you should also have a project-specific config library. An example for such a library is included in ugfx-arduino: example-ssd1351-ugfx-config. It configures uGFX through gfxconf.h, adds a display driver header, and provides configuration information for that driver. The example consists of three files.

example-ssd1351-ugfx-config.h:

#ifndef TEENSY31_SSD1351_UGFX_CONFIG_H
#define TEENSY31_SSD1351_UGFX_CONFIG_H
 
#include <ugfx-arduino.h> // main library
#include <ugfx-arduino-gdisp-ssd1351.h> // display driver library
 
#endif // TEENSY31_SSD1351_UGFX_CONFIG_H

This file just includes other headers for ugfx and a display driver.

gfxconf.h:

#ifndef _GFXCONF_H
#define _GFXCONF_H
 
/* The operating system to use. One of these must be defined - preferably in your Makefile */
//#define GFX_USE_OS_CHIBIOS	FALSE
//#define GFX_USE_OS_WIN32		FALSE
//#define GFX_USE_OS_LINUX		FALSE
//#define GFX_USE_OS_OSX		FALSE
#define GFX_USE_OS_ARDUINO      TRUE
//#define GFX_USE_OS_RAW32 TRUE
 
/* GFX sub-systems to turn on */
#define GFX_USE_GDISP			TRUE
 
/* Features for the GDISP sub-system. */
#define GDISP_NEED_VALIDATION	TRUE
#define GDISP_NEED_CLIP			TRUE
 
#endif /* _GFXCONF_H */

Just a normal ugfx configuration. Note that the selected operating system flag is GFX_USE_OS_ARDUINO.

ssd1351_pins.cpp:

#include "ugfx-arduino-gdisp-ssd1351.h"
 
extern const ssd1351_pins_t ssd1351_pins = {15, 14, 16};

This file provides pin number definitions for the display driver. The content of this file depends on the display driver.

If you want to create your own configuration for a project called myproject, you have to create a new arduino library called myproject-ugfx-config in the arduino library directory. It must at least provide one header called myproject-ugfx-config.h which includes ugfx-arduino.h and a display driver header, and it must provide gfxconf.h in the same directory. Then include myproject-ugfx-config.h in your main arduino sketch.