406 lines
13 KiB
Markdown
406 lines
13 KiB
Markdown
# Knihovna OLED_SSD (ESP8266/ESP32/SAMD21)
|
|
|
|
Jedná se o modifikovanou knihovnu pro obsluhu malých OLED displejů, připojených přes I2C, nebo SPI rozhraní. Modifikace spočívají zejména v doplnění programového kódu, umožňujícího dithering (šrafování).
|
|
|
|
|
|
Následuje mírně upravený obsah originálního README.md od původních autorů
|
|
|
|
# ThingPulse OLED SSD1306 (ESP8266/ESP32)
|
|
|
|
This is a driver for SSD1306 128x64 and 128x32 OLED displays running on the Arduino/ESP8266 & ESP32 <del>and mbed-os</del> platforms.
|
|
Can be used with either the I2C or SPI version of the display.
|
|
|
|
You can either download this library as a zip file and unpack it to your Arduino/libraries folder or find it in the Arduino library manager under "ESP8266 and ESP32 Oled Driver for SSD1306 display". For mbed-os a copy of the files are available as an mbed-os library.
|
|
|
|
## Credits
|
|
|
|
This library has initially been written by Daniel Eichhorn ([@squix78](https://github.com/squix78)). Many thanks go to Fabrice Weinberg ([@FWeinb](https://github.com/FWeinb)) for optimizing and refactoring many aspects of the library. Also many thanks to the many committers who helped to add new features and who fixed many bugs. Mbed-OS support and other improvements were contributed by Helmut Tschemernjak ([@helmut64](https://github.com/helmut64)).
|
|
|
|
The init sequence for the SSD1306 was inspired by Adafruit's library for the same display.
|
|
|
|
## Usage
|
|
|
|
Check out the examples folder for a few comprehensive demonstrations how to use the library. Also check out the [ESP8266 Weather Station](https://github.com/ThingPulse/esp8266-weather-station) library which uses the OLED library to display beautiful weather information.
|
|
|
|
## Features
|
|
|
|
* Draw pixels at given coordinates
|
|
* Draw lines from given coordinates to given coordinates
|
|
* Draw or fill a rectangle with given dimensions
|
|
* Draw Text at given coordinates:
|
|
* Define Alignment: Left, Right and Center
|
|
* Set the Fontface you want to use (see section Fonts below)
|
|
* Limit the width of the text by an amount of pixels. Before this widths will be reached, the renderer will wrap the text to a new line if possible
|
|
* Display content in automatically side scrolling carousel
|
|
* Define transition cycles
|
|
* Define how long one frame will be displayed
|
|
* Draw the different frames in callback methods
|
|
* One indicator per frame will be automatically displayed. The active frame will be displayed from inactive once
|
|
|
|
## Fonts
|
|
|
|
Fonts are defined in a proprietary but open format. You can create new font files by choosing from a given list
|
|
of open sourced Fonts from this web app: http://oleddisplay.squix.ch
|
|
Choose the font family, style and size, check the preview image and if you like what you see click the "Create" button. This will create the font array in a text area form where you can copy and paste it into a new or existing header file.
|
|
|
|
|
|
|
|
|
|
## Hardware Abstraction
|
|
|
|
The library supports different protocols to access the OLED display. Currently there is support for I2C using the built in Wire.h library, I2C by using the much faster [BRZO I2C library](https://github.com/pasko-zh/brzo_i2c) written in assembler and it also supports displays which come with the SPI interface.
|
|
|
|
### I2C with Wire.h
|
|
|
|
```C++
|
|
#include <Wire.h>
|
|
#include "SSD1306Wire.h"
|
|
|
|
// for 128x64 displays:
|
|
SSD1306Wire display(0x3c, SDA, SCL); // ADDRESS, SDA, SCL
|
|
// for 128x32 displays:
|
|
// SSD1306Wire display(0x3c, SDA, SCL, GEOMETRY_128_32); // ADDRESS, SDA, SCL, GEOMETRY_128_32 (or 128_64)
|
|
// for using 2nd Hardware I2C (if available)
|
|
// SSD1306Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_TWO); //default value is I2C_ONE if not mentioned
|
|
// By default SD1306Wire set I2C frequency to 700000, you can use set either another frequency or skip setting the frequency by providing -1 value
|
|
// SSD1306Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, 400000); //set I2C frequency to 400kHz
|
|
// SSD1306Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, -1); //skip setting the I2C bus frequency
|
|
```
|
|
|
|
for a SH1106:
|
|
```C++
|
|
#include <Wire.h>
|
|
#include "SH1106Wire.h"
|
|
|
|
SH1106Wire display(0x3c, SDA, SCL); // ADDRESS, SDA, SCL
|
|
// By default SH1106Wire set I2C frequency to 700000, you can use set either another frequency or skip setting the frequency by providing -1 value
|
|
// SH1106Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, 400000); //set I2C frequency to 400kHz
|
|
// SH1106Wire(0x3c, SDA, SCL, GEOMETRY_128_64, I2C_ONE, -1); //skip setting the I2C bus frequency
|
|
```
|
|
|
|
### I2C with brzo_i2c
|
|
|
|
```C++
|
|
#include <brzo_i2c.h>
|
|
#include "SSD1306Brzo.h"
|
|
|
|
SSD1306Brzo display(0x3c, SDA, SCL); // ADDRESS, SDA, SCL
|
|
```
|
|
or for the SH1106:
|
|
```C++
|
|
#include <brzo_i2c.h>
|
|
#include "SH1106Brzo.h"
|
|
|
|
SH1106Brzo display(0x3c, SDA, SCL); // ADDRESS, SDA, SCL
|
|
```
|
|
|
|
### SPI
|
|
|
|
```C++
|
|
#include <SPI.h>
|
|
#include "SSD1306Spi.h"
|
|
|
|
SSD1306Spi display(D0, D2, D8); // RES, DC, CS
|
|
```
|
|
or for the SH1106:
|
|
```C++
|
|
#include <SPI.h>
|
|
#include "SH1106Spi.h"
|
|
|
|
SH1106Spi display(D0, D2); // RES, DC
|
|
```
|
|
|
|
## API
|
|
|
|
### Display Control
|
|
|
|
```C++
|
|
// Initialize the display
|
|
void init();
|
|
|
|
// Free the memory used by the display
|
|
void end();
|
|
|
|
// Cycle through the initialization
|
|
void resetDisplay(void);
|
|
|
|
// Connect again to the display through I2C
|
|
void reconnect(void);
|
|
|
|
// Turn the display on
|
|
void displayOn(void);
|
|
|
|
// Turn the display offs
|
|
void displayOff(void);
|
|
|
|
// Clear the local pixel buffer
|
|
void clear(void);
|
|
|
|
// Write the buffer to the display memory
|
|
void display(void);
|
|
|
|
// Inverted display mode
|
|
void invertDisplay(void);
|
|
|
|
// Normal display mode
|
|
void normalDisplay(void);
|
|
|
|
// Set display contrast
|
|
// really low brightness & contrast: contrast = 10, precharge = 5, comdetect = 0
|
|
// normal brightness & contrast: contrast = 100
|
|
void setContrast(uint8_t contrast, uint8_t precharge = 241, uint8_t comdetect = 64);
|
|
|
|
// Convenience method to access
|
|
void setBrightness(uint8_t);
|
|
|
|
// Turn the display upside down
|
|
void flipScreenVertically();
|
|
|
|
// Draw the screen mirrored
|
|
void mirrorScreen();
|
|
```
|
|
|
|
## Pixel drawing
|
|
|
|
```C++
|
|
|
|
/* Drawing functions */
|
|
// Sets the color of all pixel operations
|
|
// color : BLACK, WHITE, INVERSE
|
|
void setColor(OLEDDISPLAY_COLOR color);
|
|
|
|
// Draw a pixel at given position
|
|
void setPixel(int16_t x, int16_t y);
|
|
|
|
// Draw a line from position 0 to position 1
|
|
void drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1);
|
|
|
|
// Draw the border of a rectangle at the given location
|
|
void drawRect(int16_t x, int16_t y, int16_t width, int16_t height);
|
|
|
|
// Fill the rectangle
|
|
void fillRect(int16_t x, int16_t y, int16_t width, int16_t height);
|
|
|
|
// Draw the border of a circle
|
|
void drawCircle(int16_t x, int16_t y, int16_t radius);
|
|
|
|
// Fill circle
|
|
void fillCircle(int16_t x, int16_t y, int16_t radius);
|
|
|
|
// Draw a line horizontally
|
|
void drawHorizontalLine(int16_t x, int16_t y, int16_t length);
|
|
|
|
// Draw a lin vertically
|
|
void drawVerticalLine(int16_t x, int16_t y, int16_t length);
|
|
|
|
// Draws a rounded progress bar with the outer dimensions given by width and height. Progress is
|
|
// a unsigned byte value between 0 and 100
|
|
void drawProgressBar(uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t progress);
|
|
|
|
// Draw a bitmap in the internal image format
|
|
void drawFastImage(int16_t x, int16_t y, int16_t width, int16_t height, const uint8_t *image);
|
|
|
|
// Draw a XBM
|
|
void drawXbm(int16_t x, int16_t y, int16_t width, int16_t height, const char* xbm);
|
|
```
|
|
|
|
## Text operations
|
|
|
|
``` C++
|
|
void drawString(int16_t x, int16_t y, String text);
|
|
|
|
// Draws a String with a maximum width at the given location.
|
|
// If the given String is wider than the specified width
|
|
// The text will be wrapped to the next line at a space or dash
|
|
void drawStringMaxWidth(int16_t x, int16_t y, int16_t maxLineWidth, String text);
|
|
|
|
// Returns the width of the const char* with the current
|
|
// font settings
|
|
uint16_t getStringWidth(const char* text, uint16_t length);
|
|
|
|
// Convencience method for the const char version
|
|
uint16_t getStringWidth(String text);
|
|
|
|
// Specifies relative to which anchor point
|
|
// the text is rendered. Available constants:
|
|
// TEXT_ALIGN_LEFT, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT, TEXT_ALIGN_CENTER_BOTH
|
|
void setTextAlignment(OLEDDISPLAY_TEXT_ALIGNMENT textAlignment);
|
|
|
|
// Sets the current font. Available default fonts
|
|
// ArialMT_Plain_10, ArialMT_Plain_16, ArialMT_Plain_24
|
|
// Or create one with the font tool at http://oleddisplay.squix.ch
|
|
void setFont(const uint8_t* fontData);
|
|
```
|
|
|
|
## Ui Library (OLEDDisplayUi)
|
|
|
|
The Ui Library is used to provide a basic set of Ui elements called, `Frames` and `Overlays`. A `Frame` is used to provide
|
|
information the default behaviour is to display a `Frame` for a defined time and than move to the next. The library also provides an `Indicator` that will be updated accordingly. An `Overlay` on the other hand is a pieces of information (e.g. a clock) that is displayed always at the same position.
|
|
|
|
|
|
```C++
|
|
/**
|
|
* Initialise the display
|
|
*/
|
|
void init();
|
|
|
|
/**
|
|
* Configure the internal used target FPS
|
|
*/
|
|
void setTargetFPS(uint8_t fps);
|
|
|
|
/**
|
|
* Enable automatic transition to next frame after the some time can be configured with
|
|
* `setTimePerFrame` and `setTimePerTransition`.
|
|
*/
|
|
void enableAutoTransition();
|
|
|
|
/**
|
|
* Disable automatic transition to next frame.
|
|
*/
|
|
void disableAutoTransition();
|
|
|
|
/**
|
|
* Set the direction if the automatic transitioning
|
|
*/
|
|
void setAutoTransitionForwards();
|
|
void setAutoTransitionBackwards();
|
|
|
|
/**
|
|
* Set the approx. time a frame is displayed
|
|
*/
|
|
void setTimePerFrame(uint16_t time);
|
|
|
|
/**
|
|
* Set the approx. time a transition will take
|
|
*/
|
|
void setTimePerTransition(uint16_t time);
|
|
|
|
/**
|
|
* Draw the indicator.
|
|
* This is the default state for all frames if
|
|
* the indicator was hidden on the previous frame
|
|
* it will be slided in.
|
|
*/
|
|
void enableIndicator();
|
|
|
|
/**
|
|
* Don't draw the indicator.
|
|
* This will slide out the indicator
|
|
* when transitioning to the next frame.
|
|
*/
|
|
void disableIndicator();
|
|
|
|
/**
|
|
* Enable drawing of all indicators.
|
|
*/
|
|
void enableAllIndicators();
|
|
|
|
/**
|
|
* Disable drawing of all indicators.
|
|
*/
|
|
void disableAllIndicators();
|
|
|
|
/**
|
|
* Set the position of the indicator bar.
|
|
*/
|
|
void setIndicatorPosition(IndicatorPosition pos);
|
|
|
|
/**
|
|
* Set the direction of the indicator bar. Defining the order of frames ASCENDING / DESCENDING
|
|
*/
|
|
void setIndicatorDirection(IndicatorDirection dir);
|
|
|
|
/**
|
|
* Set the symbol to indicate an active frame in the indicator bar.
|
|
*/
|
|
void setActiveSymbol(const char* symbol);
|
|
|
|
/**
|
|
* Set the symbol to indicate an inactive frame in the indicator bar.
|
|
*/
|
|
void setInactiveSymbol(const char* symbol);
|
|
|
|
/**
|
|
* Configure what animation is used to transition from one frame to another
|
|
*/
|
|
void setFrameAnimation(AnimationDirection dir);
|
|
|
|
/**
|
|
* Add frame drawing functions
|
|
*/
|
|
void setFrames(FrameCallback* frameFunctions, uint8_t frameCount);
|
|
|
|
/**
|
|
* Add overlays drawing functions that are draw independent of the Frames
|
|
*/
|
|
void setOverlays(OverlayCallback* overlayFunctions, uint8_t overlayCount);
|
|
|
|
/**
|
|
* Set the function that will draw each step
|
|
* in the loading animation
|
|
*/
|
|
void setLoadingDrawFunction(LoadingDrawFunction loadingDrawFunction);
|
|
|
|
/**
|
|
* Run the loading process
|
|
*/
|
|
void runLoadingProcess(LoadingStage* stages, uint8_t stagesCount);
|
|
|
|
// Manuell Controll
|
|
void nextFrame();
|
|
void previousFrame();
|
|
|
|
/**
|
|
* Switch without transition to frame `frame`.
|
|
*/
|
|
void switchToFrame(uint8_t frame);
|
|
|
|
/**
|
|
* Transition to frame `frame`, when the `frame` number is bigger than the current
|
|
* frame the forward animation will be used, otherwise the backwards animation is used.
|
|
*/
|
|
void transitionToFrame(uint8_t frame);
|
|
|
|
// State Info
|
|
OLEDDisplayUiState* getUiState();
|
|
|
|
// This needs to be called in the main loop
|
|
// the returned value is the remaining time (in ms)
|
|
// you have to draw after drawing to keep the frame budget.
|
|
int8_t update();
|
|
```
|
|
|
|
## Example: SSD1306Demo
|
|
|
|
### Frame 1
|
|
|
|
|
|
This frame shows three things:
|
|
* How to draw an xbm image
|
|
* How to draw a static text which is not moved by the frame transition
|
|
* The active/inactive frame indicators
|
|
|
|
### Frame 2
|
|
|
|
|
|
Currently there are one fontface with three sizes included in the library: Arial 10, 16 and 24. Once the converter is published you will be able to convert any ttf font into the used format.
|
|
|
|
### Frame 3
|
|
|
|
|
|
|
|
This frame demonstrates the text alignment. The coordinates in the frame show relative to which position the texts have been rendered.
|
|
|
|
### Frame 4
|
|
|
|
|
|
|
|
This shows how to use define a maximum width after which the driver automatically wraps a word to the next line. This comes in very handy if you have longer texts to display.
|
|
|
|
### SPI version
|
|
|
|
|
|
|
|
This shows the code working on the SPI version of the display. See demo code for ESP8266 pins used.
|