-
Notifications
You must be signed in to change notification settings - Fork 19
Function Reference
This is a reference to the functions supported by the FTOLED library.
For a more general getting started guide, see Using FTOLED.
The OLED class defines the following methods:
OLED(byte pin_ncs, byte pin_dc, byte pin_reset)
The constructor provides the pin numbers for the CS, DC and Reset pins (all user configurable.)
The OLED display should be declared as a global variable in the sketch, and these constructor arguments should be provided in the same place. ie:
const byte pin_cs = 7;
const byte pin_dc = 2;
const byte pin_reset = 3;
OLED oled(pin_cs, pin_dc, pin_reset);
void begin()
The begin() method must be called to initialise the display before using it. You would usually call this from your sketch's setup() method.
Calling this method again (not recommended) will reset the display.
setPixel(const byte x, const byte y, const OLED_Colour colour);
Set the colour of a single pixel at coordinates (x,y).
fillScreen(const OLED_Colour);
Fills the screen with a single colour.
drawLine( int x1, int y1, int x2, int y2, OLED_Colour colour );
Draw a line, one pixel wide, from coordinates (x1,y1) to (x2,y2) in the chosen colour.
drawBox( int x1, int y1, int x2, int y2, int edgeWidth, OLED_Colour colour);
Draw an outline of a box (rectangle) with opposite corners at coordinates (x1,y1) and (x2,y2) The lines making up the box are edgeWidth pixels wide.
drawFilledBox( int x1, int y1, int x2, int y2, OLED_Colour fillColour)
drawFilledBox( int x1, int y1, int x2, int y2, OLED_Colour fillColour, int edgeWidth, OLED_Colour edgeColour)
Draw a filled box (rectangle) with opposite corners at coordinates (x1,y1) and (x2,y2). The box will be drawn in fillColour.
For example, to draw a red box that takes up 3/4 of the screen:
oled.drawFilledBox(32,32,96,96,RED);
The second form of this function optionally draws separate coloured lines around the edges of the box, edgeWidth pixels wide in edgeColour.
drawCircle( int xCenter, int yCenter, int radius, OLED_Colour colour)
Draw a one pixel wide outline of a circle, centered at coordinates (xCenter, yCenter) with the specified radius and colour.
drawFilledCircle( int xCenter, int yCenter, int radius, OLED_Colour fillColour)
Draw a filled circle at the specified coordinates and with the specified radius and colour.
See Displaying Text for a full explanation of text rendering with FTOLED.
selectFont(const uint8_t* font);
Changes the currently selected font. See Displaying Text for details.
drawString(int x, int y, const char *bChars, OLED_Colour foreground, OLED_Colour background)
Draw the specified string bChars starting at (x,y) (bottom-left corner) and using the specified foreground and background colours. See Displaying Text for details.
int drawChar(const int x, const int y, const char letter, const OLED_Colour colour, const OLED_Colour background)
Draw a single character letter at the specified coordinates, using the specified foreground and background colours and the currently selected font.
Returns an int value which is the width (in pixels) of the character.
int charWidth(const char letter)
Returns the width (in pixels) of the character letter in the currently selected font.
Returns 0 if the character is not represented in the currently selected font.
BMP_Status displayBMP(File &source, const int x, const int y);
BMP_Status displayBMP(File &source, const int from_x, const int from_y, const int to_x, const int to_y)
BMP_Status displayBMP(const uint8_t *pgm_addr, const int x, const int y)
BMP_Status displayBMP(const uint8_t *pgm_addr, const int from_x, const int from_y, const int to_x, const int to_y)
See the Displaying BMPs page for details on using these functions.
The SSD1351 controller in the OLED128 supports user-programmable pixel intensities via the "grayscale table". The "grayscale table" also determines gamma.
FTOLED supports three default pixel intensity levels:
setDefaultGrayscaleTable();
setBrightGrayscaleTable();
setDimGrayscaleTable();
Calling setBrightGrayscaleTable() or setDimGrayscaleTable() will result in a display that is slightly brighter or somewhat dimmer than the default.
It is also possible to set a totally custom greyscale table. This is a feature for advanced users only:
setGrayscaleTable_P(const byte *table);
"table" must be the address of a PROGMEM table holding 64 grayscale level values (GS0..GS63), which must be strictly incrementing. Values in the table can have values 0-180. See the SSD1351 controller datasheet, especially section 8.8, for more details.
You can call
clearScreen()
To return the screen to all-black.
void setDisplayOn(bool on);
You can call setDisplayOn(false) to put the display output off, and setDisplayOn(true) to switch it back on.
This method uses less power than simply setting the screen to all-black, and it also preserves whatever is on the display.
void setOrientation(OLED_Orientation orientation)
enum OLED_Orientation {
ROTATE_0 = 0,
ROTATE_90 = 1,
ROTATE_180 = 2,
ROTATE_270 = 3
};
The OLED display defaults to a default orientation (ROTATE_0), which has the top of the display level with the rear connector (as shown in all drawings of the OLED128 module.) It is also possible to rotate the display in 90 degree clockwise steps, by calling setOrientation() with the ROTATE_90, ROTATE_180 or ROTATE_270 values.
It is recommended you set the orientation immediately after calling oled.begin(). For example, to rotate 180 degrees (upside down):
void setup()
{
oled.begin();
oled.setOrientation(ROTATE_180);
}
There is no performance overhead from using a non-default rotation (the rotations are mostly handled by the display controller.)
You can change orientations after the screen is already displaying an image, but it's recommended that you call clearScreen() or fillScreen() to blank the screen immediately after changing orientation, then redraw.
If you're changing orientations by 180 degrees (ie ROTATE_0 to/from ROTATE_180 or ROTATE_90 to/from ROTATE_270) then it is actually possible to retain what is currently on the screen (rotated to match the new orientation), rather than having to redraw it. However the new rotation won't take effect until you update at least one pixel on the screen.
setDisplayMode(OLED_Display_Mode mode)
Where mode can be any of:
-
DISPLAY_OFF- All pixels turned off (screen black.) -
DISPLAY_ALL_PIXELS_FULL- All pixels at maximum brightness. -
DISPLAY_NORMAL- All pixels set to normal output. -
DISPLAY_INVERSE- Invert the display (ie black is white, white is black.)
OLED128 has a single GPIO ("General Purpose Input Output") pin #1 broken out to a through hole pad on the back of the module. Due to the controller configuration this pin can be used as an output only.
The output is disabled (high impedance) by default but it is possible to set it to HIGH (3V - 3.3V) or LOW (0V - 0.3V) level outputs
Note that the GPIO is part of the SSD1351 OLED controller and is not a high current output, you should limit any source or sink currents to 2mA max.
setGPIO1(OLED_GPIO_Mode gpio1);
Valid values are OLED_HIZ (disabled), OLED_HIGH and OLED_LOW.
(The SSD1351 also supports a second GPIO pin, GPIO0, but this is used internally by the OLED128 module.)