OLED - Programming

[last update: 2024-09-04]
OLED - Fonts
OLED - Overview/Specs
-----

Did I mention I don't really know what I'm doing?
These notes and instructions are things I've gotten off the web (many that I haven't personally tested),
or things I've tried, and know that they do work.

• Set up the OLED:
  • includes:
    #include <Adafruit_SSD1306.h> // the main library for the display

    This seems to be the minimum sufficient library to include, however I've never seen it used just by itself.
    It's always used along with other libraries:

    #include <Adafruit_GFX.h>
        and often:
    #include <Adafruit_TFTLCD.h>
    #include <Wire.h>

    Plus, if you want any special fonts, you must include them as well, eg:

    #include <Fonts/FreeSans9pt7b.h>

    However, if all you want to do is send default text to your screen, then the SSD1306 library is sufficient to make it work.

  • in globals, declare the screen object:
    // for OLED display:
    #define SCREEN_WIDTH 128 // OLED display width, in pixels
    #define SCREEN_HEIGHT 32 // OLED display height, in pixels
    // Declaration for an SSD1306 display connected to I2C (SDA, SCL pins)
    #define OLED_RESET 4 // Reset pin # (or -1 if sharing Arduino reset pin)
    Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

  ----------------------------------------------------------------

• Put something on the screen:
  • Basic syntax:
    • Set up the parameters for whatever you want to display, whether graphics or text, then:
      display.display(); // to send it to the display
    • All commands must be followed by display.display() in order to execute them.
      (Except scroll text commands ... see below)

    ----------------------------------------------

  • General commands:
    • display.clearDisplay(); // ??? does NOT clear the display?? only clears the buffer???
    • display.invertDisplay(true); // changes white to black, & black to white
      display.invertDisplay(false); // changes it back
    • display.setRotation(2); //rotates graphics and text: 0 = 0 deg, 1 = 90 deg, 2 = 180 deg

    ----------------------------------------------

  • Text: define content, size, color, font, & position, then send it to the screen:
    • There are two commands to put text onto the screen:
      • display.write();
        display.write(75); // will put "K" (ascii 75) onto the screen

        you can give it hex as well:

        display.write(0x4A);

        But it will only do a single character at a time.

        display.write(10); // does a LF (skips to next line)
      • display.print();
        • display.print("abcd"); // puts the quoted text to the screen
        • You must set textsize before executing print.
        • Text will automatically wrap to next line, eg:
          printing "ABCDEFGHIJKLMN" in size 2
                will print A - J on first line, and the remainder on the second

      --------------------

    • Specify text parameters
      before you put it onto the screen:
      • Set text color:
        display.setTextColor(SSD1306_WHITE); // Draw white text; my module (ADA:4440) is only monochrome white
      • Set text size:
        display.setTextSize(n); // n=1 is "normal 1:1 pixel scale", 2 is twice as large, and 3 is the largest that will fit on my 128x32 screen
      • Set text position:
        display.setCursor(0, 0); // Start at top-left corner

      • Set text font:
        • If you have characters that you want to print
          that are Not just alphanumeric and standard punctuation,
          for example the temperature "degree" symbol, then you must use this command:
          display.cp437(true); // Set fontface to full 256 char 'Code Page 437' font
          FYI the temperature degree symbol is printed to the screen with:
          display.write(167);

        • To use a different font, you must first have "included" it at the top of your program, eg:
          #include <Fonts/FreeSans9pt7b.h>

          Then to invoke/activate/select it, before you do your print or write statements, do this:

          display.setFont(&FreeSans9pt7b);

          See: OLED - Fonts for a list of just some of the many fonts available.

        • Return to default (tiny) font:
          display.setFont(NULL);
    • Scrolling text:
      • options:
        display.startscrollright(0x00, 0x0F);
        display.startscrollleft(0x00, 0x0F);
        display.startscrolldiagright(0x00, 0x07);
        display.startscrolldiagleft(0x00, 0x07);
      • display.stopscroll();
      • you must do the usual display.display(); when inititially displaying the text you want to scroll,
        but do not need to repeat it after doing scroll commands.
    • Gotcha
      • If you have written some text to the screen,
        and now you want to write new text to replace the old,
        and you Don't want to do a complete clearScreen,
      • (You'd think you could) just position the cursor where you want it, where the original text is located,
        and print the new text.
      • However:
        the new text will only write pixels sufficient to define the character,
        and will NOT write background colors where there are no pixels for the character.
        Supposedly you can define the background color in your write command [... how/examples?...]
        but this only works with some fonts, or some libraries, or some screens, IDK,
        in any case it did NOT work for mine, ...
      • So the solution is to draw a background color rectangle to cover the first text to effectively "erase" it:
        display.fillRect(x, y, w, h, color);
        followed of course as always with display.display();
        For my 128x32 display, with a 1-px border,
            this is the largest rect I could draw to clear the center without over-writing the border:
                display.fillRect(1, 1, 126, 30, BLACK); // clear center of screen
        Supposedly there is a getBounds command that will help you define x, y, w, & h, but I haven't researched/found it ...

    ----------------------------------------------

  • Graphics:
    • display.drawPixel(x, y, SSD1306_WHITE); // puts pixel at x, y location
      max pixel range is (0, 0) to (127, 32) regardless that you can draw a rectangle to x=128 (see below)
    • display.drawRect(0, 0, 128, 32, SSD1306_WHITE); // draws largest rectangle for my screen size

    • display.drawBitmap(....); // need more study to understand how to use this ...

  ----------------------------------------------

• other stuff to review, incorporate, discard ...
  • Links:
    https://learn.adafruit.com/adafruit-gfx-graphics-library/graphics-primit...

.

.

.

eof