Writing C++ Code for Displays

Using a Classic IDE Like Arduino IDE or PlatformIO to Write Firmware That Controls Displays

Using a classic IDE and writing your own firmware to control a display is simple and straightforward, thanks to excellent libraries that provide easy access to display hardware.

Overview

The key to programming a display with C++ is finding and understanding a good library that is compatible with your specific display.

Display Driver

Your software does not interact directly with the display hardware but rather with the display driver it uses. To find the right library, you need to determine the name of the driver your display is based on.

If you don’t know the driver:

  1. Identify the display type first (e.g., TFT, OLED, e-Ink, LCD).
  2. Visit the appropriate sections: TFT, OLED. Each section lists commonly used drivers, such as the ILI9341, the more modern ST7789, or widely used monochrome OLED drivers like SH1106 and the older but more capable SSD1306.
  3. Each driver section includes a list of display boards that use that driver. Browse through them until you find a match for your display board.

Choosing the Right Display Library

Finding the best library for your display may seem overwhelming at first due to the sheer number of options available.

Avoid Cloned Libraries

One reason for this abundance of libraries is that users frequently clone well-established libraries to make minor adjustments or add specific features for their projects. These modified versions (forks) often become outdated and are not actively maintained.

For long-term reliability and access to updates, always prioritize the original library from its primary author. The original developers are typically committed to maintaining and improving their libraries over time, whereas cloned versions often remain as static snapshots with minor modifications.

Choose a Library Based on Your Project Needs

Not all libraries follow the same approach. Different libraries offer unique design philosophies, optimizations, and trade-offs. Understanding these differences will help you select the most suitable library for your specific application.

Evaluate the strengths and weaknesses of each approach, consider how they align with your project goals, and make an informed decision.

Universal Libraries

There are several universal libraries that support a wide range of displays:

  • Monochrome Displays: u8g2 supports a vast number of monochrome displays, including both TFT and OLED.
  • Color Displays: ucglib provides support for numerous color displays, covering both TFT and OLED technologies.
  • TFT Displays: TFT-eSPI is optimized for SPI-based TFT displays, supporting both monochrome and color variants.

Using these libraries is straightforward: a single library can handle many different displays. If you decide to change your display hardware later, you typically only need to adjust the constructor or modify configuration settings, without rewriting large parts of your code.

Specific Libraries

In contrast, specific libraries are designed to support a single display driver. These libraries are often easier to use because they are tailored specifically for your display, eliminating the need for extensive configuration.

However, the main drawback of specific libraries is that they lock your code into a particular display model. If you later switch to a different display, you may need to rewrite significant portions of your code.

To address this issue, Adafruit introduced a smart approach: it provides hardware-specific libraries for all popular display drivers.

| Display Type | Library Name & Link | Supported Displays | |———————-|——————————————————-|————————————————-| | OLED Displays | Adafruit SSD1306 | 128x64 and 128x32 monochrome OLEDs | | | Adafruit SH1106 | SH1106-based OLEDs (e.g., 128x64 resolution) | | TFT and LCD Displays | Adafruit ILI9341 | ILI9341-based 320x240 TFT displays | | | Adafruit ST7735 and ST7789 | ST7735 and ST7789-based TFT displays | | | Adafruit ILI9486 | ILI9486-based TFTs, often 480x320 resolution | | | Adafruit HX8357 | HX8357-based TFT displays | | E-Paper Displays | Adafruit EPD | Supports various ePaper (E Ink) displays | | Monochrome LCDs | Adafruit PCD8544 | Nokia 5110 LCDs (84x48) | | | Adafruit ST7565 | ST7565-based graphic LCDs | These libraries focus solely on display hardware and do not include high-level graphics functions for rendering text or drawing shapes.

All drawing functionality is handled by a separate hardware-neutral library: Adafruit GFX Library.

Thanks to this modular approach, you can use highly specific display driver libraries that require minimal configuration while keeping your source code display-independent. If you later switch to a different display, you only need to replace the hardware-specific display library—your source code remains unchanged.

Using platformio

PlatformIO is a modern and highly capable development environment available as a free extension for VSCode, Microsoft’s free code editor. It supports Windows, Linux, and macOS.

Compared to Arduino IDE, PlatformIO has a steeper learning curve but offers significantly more power and flexibility.

Source Code Compatibility

PlatformIO generates standard C++ source code, whereas Arduino IDE introduces custom leniencies and private rules that are not part of the C++ standard. This can cause compatibility issues when using Arduino IDE code in PlatformIO, as is often the case with examples found online.

Fortunately, adapting Arduino IDE code for PlatformIO is straightforward. Once the necessary adjustments are made, Arduino IDE code runs seamlessly in PlatformIO.

Key Adjustments for Compatibility

  • Rename .ino to .cpp:
    Arduino IDE uses the .ino file extension (derived from Arduino) for C++ source files, while the standard extension is .cpp (from C++). Simply rename your file to match this standard.

  • Explicitly include Arduino.h:
    Arduino IDE automatically includes Arduino.h, but in PlatformIO, you must add #include <Arduino.h> at the top of your code.

  • Ensure setup() and loop() exist:
    Both setup() and loop() must be defined. If loop() is unnecessary, define an empty function to prevent errors.

  • Correct function order:
    Arduino IDE allows calling functions before they are defined, but PlatformIO follows standard C++ rules. Place setup() at the bottom of your code and ensure all functions are defined before they are called to avoid “undefined function” errors.

Slow Website?

This website is very fast, and pages should appear instantly. If this site is slow for you, then your routing may be messed up, and this issue does not only affect done.land, but potentially a few other websites and downloads as well. Here are simple steps to speed up your Internet experience and fix issues with slow websites and downloads..

Comments

Please do leave comments below. I am using utteran.ce, an open-source and ad-free light-weight commenting system.

Here is how your comments are stored

Whenever you leave a comment, a new github issue is created on your behalf.

  • All comments become trackable issues in the Github Issues section, and I (and you) can follow up on them.

  • There is no third-party provider, no disrupting ads, and everything remains transparent inside github.

Github Users Yes, Spammers No

To keep spammers out and comments attributable, all you do is log in using your (free) github account and grant utteranc.es the permission to submit issues on your behalf.

If you don’t have a github account yet, go get yourself one - it’s free and simple.

If for any reason you do not feel comfortable with letting the commenting system submit issues for you, then visit Github Issues directly, i.e. by clicking the red button Submit Issue at the bottom of each page, and submit your issue manually. You control everything.

Discussions

For chit-chat and quick questions, feel free to visit and participate in Discussions. They work much like classic forums or bulletin boards. Just keep in mind: your valued input isn’t equally well trackable there.

  Show on Github    Submit Issue

(content created Jan 22, 2025)