ESP8266/ESP32 SSD1306和SH1106 OLED驱动函数说明

ESP8266/ESP32 SSD1306和SH1106 OLED驱动函数说明

---

• 📌 SSD1306和SH1106 OLED驱动库：https://github.com/ThingPulse/esp8266-oled-ssd1306
• 📌在线生成字体库：https://oleddisplay.squix.ch/
• 显示

在给定坐标绘制像素
从给定坐标到给定坐标画直线
用给定的尺寸绘制或填充矩形
在给定坐标绘制文本：
定义对齐方式：左对齐、右对齐和居中对齐
设置要使用的字体（请参阅下面的字体部分）
将文本宽度限制为像素量。在达到此宽度之前，如果可能，渲染器会将文本换行
在自动侧滚式旋转显示内容
定义过渡周期
定义一个帧的显示时间
在回调方法中绘制不同的帧
每帧将自动显示一个指示器。激活帧将从非活动状态显示一次

• 字体

字体是以一种专有但开放的格式定义的。
您可以通过从该web应用程序的开放源代码字体列表中选择来创建新的字体文件：
[http://oleddisplay.squix.ch](http://oleddisplay.squix.ch)
选择字体系列、样式和大小，检查预览图像，
如果您喜欢所看到的内容，请单击“创建”按钮。
这将在文本区域表单中创建字体数组，
您可以在其中复制并粘贴到新的或现有的头文件中。

该库支持访问OLED显示器的不同协议。目前支持使用内置Wire.h库的I2C，使用汇编程序编写的更快的brzoi2c库来支持I2C，它还支持SPI接口附带的显示器。

• I2C带Wire.h

#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

• 对于SH1106：

#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

• 对于SPI

#include <SPI.h>
#include "SSD1306Spi.h"
SSD1306Spi display(D0, D2, D8);  // RES, DC, CS

对于SH1106

include <SPI.h>
#include "SH1106Spi.h"
SH1106Spi display(D0, D2);  // RES, DC

API
Display Control

/ 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

/* 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

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库（OLEDDisplayUi）
  Ui库用于提供一组称为Frames和Overlays的Ui元素。Frame用于提供信息默认行为是在定义的时间内显示Frame，然后移动到下一个时间。该库还提供了一个Indicator，它将相应地进行更新。另一方面，Overlay是一段信息（例如时钟），它总是显示在同一位置。

/**
* 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

此框架显示三件事：

如何绘制xbm图像
如何绘制不被帧转换移动的静态文本
活动/非活动帧指示器
Frame 2

目前有一个字体库包括三种尺寸：Arial 10、16和24。一旦转换器发布，你就可以将任何ttf字体转换成所使用的格式。
Frame 3

此框架演示文本对齐方式。框架中的坐标显示了文本相对于哪个位置被渲染。
Frame 4

这演示了如何使用“定义最大宽度”，在该宽度之后，驱动程序会自动将单词换行到下一行。如果要显示较长的文本，这将非常方便。
SPI version