afiskon / stm32-ssd1306

STM32 library for working with OLEDs based on SSD1306, SH1106, SH1107 and SSD1309, supports I2C and SPI

stm32-ssd1306

STM32 library for working with OLEDs based on SSD1306, supports I2C and 4-wire SPI. It also works with SH1106, SH1107 and SSD1309 which are compatible with SSD1306.

A detailed video-tutorial is available on hacksOnTable YouTube-channel. If you want to create a custom font, please read Creating Custom Fonts. For even more details please see ssd1306/ssd1306_conf_template.h and examples directory.

The code is based on 4ilo/ssd1306-stm32HAL library developed by Olivier Van den Eede ( @4ilo ) in 2016.

Ports

There is a DuyTrandeLion/nrf52-ssd1309 port to nRF52 of this library made by @DuyTrandeLion in 2020.

There is also a kirsche-ctrl/xmc2go-ssd1306 port to XMC made by @kirsche-ctrl in 2022.

Other Libraries

For other displays there are separate libraries available:

• https://github.com/afiskon/stm32-i2c-lcd-1602
• https://github.com/afiskon/stm32-ssd1351
• https://github.com/afiskon/stm32-st7735
• https://github.com/afiskon/stm32-ili9341

stm32-ssd1306's Issues

Also works with STM32F0

Tested it with a STM32F030R8 on a nucleo board using I2C.
Just #include "stm32f0xx_hal.h" in the ssd1306.h header and be sure to use 4,7k Ohm pullup resistors on the data and clock wires.

How to utlize this library for Float values ?

I am looking to add this to my RH Meter. how can i do the same ? I tried but not luck.

void ssd1306_TestFonts2() {
#ifdef SSD1306_INCLUDE_FONT_16x24
    uint8_t x1, y1, x2, y2;

    // Convert the float counter value to a string
    char counter_str[6]; // Assuming the format is XX.XX
    snprintf(counter_str, 6, "%05.2f", counter);

    ssd1306_Fill(Black);

    // Display the counter value
    ssd1306_SetCursor(0, 4);
    ssd1306_WriteString(counter_str, Font_16x24, White);

    // Other text
    ssd1306_SetCursor(0, 4+24+8);
    ssd1306_WriteString("RIT+1000", Font_16x24, White);

    // Underline
    x1 = 6*16;
    y1 = 4+24+8+24;
    x2 = x1+16;
    y2 = y1+2;
    ssd1306_FillRectangle(x1, y1, x2, y2, White);

    ssd1306_UpdateScreen();
#endif
}

How to Add Degree Celsius Symbol °C

How to Add Degree Celsius Symbol ? not getting any clue. need to add Degree Celcius.°C

Custom fonts

1. Thanks for the great job! I am using it with great joy! Perhaps there is a font editor somewhere like this: "https://www.quinapalus.com/hd44780udg.html"
2. I think the member "SSD1306.Inverted" is used without initialization. Perhaps I was mistaken when I rewrote the library to i2c_DMA_without_HAL. I found random behavior. Assigning value = 0 fixed the problem.

Adding support for nRF52

Hello,

I am using your library on STM32 and I just finished porting it for my Nordic nRF52.
May I re-upload the library and link it to your library?

Thank you and best regards,
Duy

Pull requests are not open : add compatibility for STM32L053

so I can add compatibility for those MCUs

(basicly
#elif defined(STM32L053xx)
#include "stm32l0xx_hal.h"
#endif

into SSD1306.h

Smaller bitmap images not working

I have added a bitmap draw function from adafruit library to this library when I used 128 * 64 size bitmap image evrything is fine but when I rescale it to 36 * 36 the iamge is not properly shown.

void ssd1306_DrawBitmap(int16_t x, int16_t y, const unsigned char* bitmap, int16_t width, int16_t height, uint16_t color){
  int16_t byteWidth = (width + 7) / 8; // Bitmap scanline pad = whole byte
  uint8_t byte = 0;

  for(int16_t j=0; j < height; j++, y++){
    for(int16_t i=0; i < width; i++){
      if(i & 7)
       byte <<= 1;
      else
       byte = bitmap[j * byteWidth + i / 8];
      
      if(byte & 0x80)
        ssd1306_DrawPixel(x+i, y, color);
    }
  }
}

Custom-fonts Generate not working for me

Hi,
I have been trying to get the conversion working but keep getting the following error no matter what I try. I even tried copying the font file Teko-Bold.ttf font to the same folder as the program but no success. Any help would be appreciated.

C:\temp>.\generate.py --font Teko-Bold.ttf --size 20

File "C:\temp\generate.py", line 24
    match args.charset:
             ^
SyntaxError: invalid syntax

Directory of C:\temp

02/04/2024  12:52    <DIR>          .
02/04/2024  12:52    <DIR>          ..
01/04/2024  13:01             3,375 atlas.png
01/04/2024  13:01             1,512 convert.py
01/04/2024  13:01             4,705 generate.py
01/04/2024  13:01            37,422 hd44780-large.txt
01/04/2024  13:01             3,852 hd44780-small.txt
01/04/2024  13:01             2,638 README.md
01/04/2024  13:01               231 string.png
25/08/2023  18:51           154,868 Teko-Bold.ttf
01/04/2024  13:01             1,468 upscale.py
               9 File(s)        210,071 bytes

Works great!

Just want to say thanks for this! I tried some other libraries and they gave me a head-ache, this one works great and I love the clean and well commented code!

I use this on a custom STM32F401RC.

[Duplicate] How can i create new font for SSD1306 OLED LCD ?

Hi,
Can you please let me know which software which you used to create fonts for this LCD module ?
Thanks !

Possible endless cycle

stm32-ssd1306/ssd1306/ssd1306.c

Line 541 in 11c0234

void ssd1306_FillRectangle(uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2, SSD1306_COLOR color) {

Hi. If someone tries to draw filled rectangle with coordinates starting with 0,0 (ex. FillRectangle(0,0,10,10,Black), he or she will be surprised. Program gets in an endless cycle.

for (uint8_t y = y2; y >= y1; y--) {
        for (uint8_t x = x2; x >= x1; x--) {
            ssd1306_DrawPixel(x, y, color);
        }
    }

Imagine x1=0 and x is constantly decreasing after each cycle.

1. x=1, 1>=0 - true
2. x=0, 0>=0 - true
3. x=255, 255>=0 -true. "x" is an unsigned var.
   And so on.

By the way, I didn't search for problems in other similar functions. Maybe they should be reconsidered.

SPI & STM32 CLK frequency

Hello
thanks for sharing your code,
I am new and learning to initialize ssd1306 OLED module which can run at 8 MHz with SPI interface ,

When testing with SPI interface :

• Did you test the code on STM32 running at 16MHz (using HSI clock source) or some other frequency / other clock source ?
• What's the clock frequency on your (SCL) ssd1306 OLED ?

because in this line of code I saw the baudrate scaler is set to 64.
I have not figured out how to calculate for correct SPI clock.

could you please give some tips / hints ?
thanks for your help

Fonts

Hey Guys ,
IS there any program to generate fonts , i want to import a custom font that i want, is this possible??

[Duplicate] How to convert fonts to 16bits ?

May I ask what software did you use to convert the font to 16bits format?
code as shown below：

static const uint16_t Font7x10 [] = {
0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // sp
0x1000, 0x1000, 0x1000, 0x1000, 0x1000, 0x1000, 0x0000, 0x1000, 0x0000, 0x0000, // !
0x2800, 0x2800, 0x2800, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // "
0x2400, 0x2400, 0x7C00, 0x2400, 0x4800, 0x7C00, 0x4800, 0x4800, 0x0000, 0x0000, // #
0x3800, 0x5400, 0x5000, 0x3800, 0x1400, 0x5400, 0x5400, 0x3800, 0x1000, 0x0000, // $

Adding rotation for the screen

Hello,

I would like to add rotation for the screen such as 0 degree, 90 degrees, 180 degrees. 270 degrees. Where can I modify?

Thanks and best regards,
Duy

Add support for STM32G0

I have added PR for STM32G0 mcu to use this library.

Support for more display resolutions (SH1107 support)

Hello, thanks for taking the time to put together this library!

I'm trying to use this library with this 1.12" OLED breakout from Pimoroni
which uses the SH1106 controller. The display has a resolution
of 128x128 which exceeds the maximum height supported by this
library. This is the error displayed when I attempt to set the
SSD1306_HEIGHT to 128:

`error: #error "Only 32 or 64 lines of height are supported!"`

Are there plans to support additional display resolutions? I'm
also more than happy to try and contribute the feature - although
I'm very new to embedded development so I'll need some pointers!

Port to Maxim 326x

I am working on a port to another ARM platform (Maxim 326x) and have integrated with the Maxim I2C library. Coms look good and the OLED is ACKing but I am not seeing any activity on the display.

I've tried a number of the tests (after init) with no success. If anyone has a suggestion on what I might want to tweak on the default init and tests, I am open to suggestions.

Thanks!

Bidirectional SPI doesn't work with SSD1306

I tried to configure SPI as done in the example

stm32-ssd1306/examples/oled-tester/firmware/spi/Src/main.c

Line 187 in dfb3dab

hspi1.Init.Direction = SPI_DIRECTION_1LINE;

But I discovered that with each transmission an extra impulse appears, which confuses the display. Perhaps in the example, due to the high frequency of the controller, this does not lead to a failure, but at a low frequency the screen stops working.

Disabling bidirectional mode solves the problem.

JFYI works with STM32F3

#include <stddef.h>

#if defined(STM32F1)
#include "stm32f1xx_hal.h"
#elif defined(STM32F4)
#include "stm32f4xx_hal.h"
#elif defined(STM32L4)
#include "stm32l4xx_hal.h"
#elif defined(STM32F3)
#include "stm32f3xx_hal.h"
#else
 #error "SSD1306 library was tested only on STM32F1, STM32F3, STM32F4, STM32L4 MCU families. Please modify ssd1306.h if you know what you are doing. Also please send a pull request if it turns out the library works on other MCU's as well!"
#endif

Support for STM32C0XX Series MCU

First, I'm not familiar with the 'how to' of doing a pull request, as I'm not at all familiar with github, and I don't want to remotely come close to breaking anything. I'm hoping this is proper venue for this.

The STM32C0XX Series is the latest low-cost line of MCU from ST. I got the SPI interface working by adding the following to the header files.

In the ssd1306_conf.h you can add this to the list of MCU #define list

#define STM32C0

and in ssd1306.h the following can be added at the end of the MCU choices

#elif defined(STM32C0)
#include "stm32c0xx_hal.h"

and aside from realizing you need to start with the reset/DC/CS pins high, it worked without a problem.

Set memory addres mode

Hello, in code i see this:
ssd1306_WriteCommand(0x20);//Set Memory Addressing Mode
ssd1306_WriteCommand(0x10); // 00,Horizontal Addressing Mode; 01,Vertical Addressing Mode;
// 10,Page Addressing Mode (RESET); 11,Invalid
But datasheet say:

A[1:0] = 01b, Vertical Addressing Mode

that mean bin, not hex.
RESET state is 0b10, that mean this code not need.
P.S. Sorry for my eanglish)

Wrong comparism in ssd1306_WriteChar

stm32-ssd1306/ssd1306/ssd1306.c

Lines 191 to 196 in cf75515

	if (SSD1306_WIDTH <= (SSD1306.CurrentX + Font.FontWidth) ||
	SSD1306_HEIGHT <= (SSD1306.CurrentY + Font.FontHeight))
	{
	// Not enough space on current line
	return 0;
	}

I think both "<=" must be only "<".

E.g. if you where on line 57 on a screen with 64 lines and wanted to print a 7 pixels high character: Line 57 to line 63 are exactly the 7 lines you'd need, but the check would fail because 64 <= (57 + 7) is true. The last line to use would always be SSD1306.CurrentY + Font.FontHeight - 1

You could even omit the check, because ssd1306_DrawPixel() checks it again. So you could have partial letters on the screen if you wanted to.

P.S.: Thank you for your work with this library. It worked on the first try with my STM32F401RE.

use screen as portrait mode ?

is there a way to use the screen in portrait mode not landscape mode ?

[Duplicate] How to generate fonts for uint16_t?

How to generate fonts for uint16_t?

Solution for 32row OLEDs

I've used your library for 128x32 OLED,
however it required following modifications in ssd1306_init():

    ssd1306_WriteCommand(0xA8); //--set multiplex ratio(1 to 64) - CHECK
#if SSD1306_HEIGHT==32
    ssd1306_WriteCommand(0x1F); //
#else
    ssd1306_WriteCommand(0x3F); //
#endif

and

    ssd1306_WriteCommand(0xDA); //--set com pins hardware configuration - CHECK
#if SSD1306_HEIGHT==32
    ssd1306_WriteCommand(0x02);
#else
    ssd1306_WriteCommand(0x12);
#endif

PlatformIO can't override / define macros

I'm looking to make this library compatible with platformIO and for the most part I have the library being recognized but I can't seem to override the macros

// src/main.h
#define SSD1306_USE_I2C
#define SSD1306_I2C_PORT                       hi2c1
#define SSD1306_I2C_ADDR                       (0x3C << 1)
#define SSD1306_HEIGHT                         32
#define SSD1306_WIDTH                          128

// src/main.c
#include "ssd1306.h"

These are the errors I am getting when I compile.

In file included from lib/SSD1306/ssd1306/ssd1306.c:1:0:
lib/SSD1306/ssd1306/ssd1306.h:73:2: error: #error "You should define SSD1306_USE_SPI or SSD1306_USE_I2C macro!"
 #error "You should define SSD1306_USE_SPI or SSD1306_USE_I2C macro!"
  ^~~~~
lib/SSD1306/ssd1306/ssd1306.c:49:2: error: #error "You should define SSD1306_USE_SPI or SSD1306_USE_I2C macro"
 #error "You should define SSD1306_USE_SPI or SSD1306_USE_I2C macro"
  ^~~~~
*** [.pio/build/bluepill_f103c8_128k/libec4/SSD1306/ssd1306/ssd1306.o] Error 1
Compiling .pio/build/bluepill_f103c8_128k/FrameworkHALDriver/Src/stm32f1xx_hal.o
In file included from lib/SSD1306/ssd1306/ssd1306_tests.c:1:0:
lib/SSD1306/ssd1306/ssd1306.h:73:2: error: #error "You should define SSD1306_USE_SPI or SSD1306_USE_I2C macro!"
 #error "You should define SSD1306_USE_SPI or SSD1306_USE_I2C macro!"
  ^~~~~
*** [.pio/build/bluepill_f103c8_128k/libec4/SSD1306/ssd1306/ssd1306_tests.o] Error 1

I'm going to get my own version working, but if someone would like to help me with this I can make a pull request so the platformIO community can start using it 👍

SSD1309 Support

It's a really silly question but I would like to ask anyway. The ReadMe.md claims that the library supports other drivers except ssd1306 (and specifically ssd1309).Though when I opened ssd1306_conf_template.h it doesn't seem to have any other option for other drivers I also show this suggested project https://github.com/DuyTrandeLion/nrf52-ssd1309 , but this has nothing to do with my toolchain as I use CubeMx and a Nucleo (like the examples here).Again I know it is a silly question as the library is literally named stm32-ssd1306 thank you in advance.

Test code seems hava a little bug

https://github.com/afiskon/stm32-ssd1306/blob/master/examples/oled-tester/firmware/i2c/Src/main.c#L42

[Solved] There is always a vertical line on the right side of the screen

Hi
I am honored to use your code.

There is a problem with the ssd1306 test.
I used your ssd3606 sample code and connected the ssd1306 using SPI.
The code runs almost perfectly on SSD1306.
However, there is always a vertical line on the right side of the screen.

Any code fixes?

SH1106 compatibility

I notice that this library hasn't acquired full compatibility between SSD1306 and SH1106 drivers yet. As I researched online, I found out that there's a difference between the RAMs of SSD1306 and SH1106 drivers. This could be resolve simply by adding a macro (i.e. SH1106_DRIVER) in ssd1306_conf.h file. If user enables this macro, SSD1306_WIDTH should be 130 for OLEDs with a 128-px width. In ssd1306_DrawPixel(..) function in ssd1306.c, the index for SSD1306_Buffer then becomes x + 2 + (y / 8) * SSD1306_WIDTH as follows:

// Draw in the right color
    #if defined(SH1106_DRIVER)
    if(color == White) {
        SSD1306_Buffer[x + 2 + (y / 8) * SSD1306_WIDTH] |= 1 << (y % 8);
    } else { 
        SSD1306_Buffer[x + 2 + (y / 8) * SSD1306_WIDTH] &= ~(1 << (y % 8));
    }
    #else
    if(color == White) {
        SSD1306_Buffer[x + (y / 8) * SSD1306_WIDTH] |= 1 << (y % 8);
    } else { 
        SSD1306_Buffer[x + (y / 8) * SSD1306_WIDTH] &= ~(1 << (y % 8));
    }
    #endif

[Duplicate] how to create new fonts ?

Hi,
Thank for your library so much !
It's work fine on STM32F4 MCUs.
But, can you please let me know how can i create new fonts ? Which software is used ?
Thanks !

last 2 pixels at RHS of display remain on after reset

I am new to this so most probably the error on my part.

I have setup a 128x64 display with a blue pill running this software. I have watched the YouTube video several times to see if I have missed anything. In fact ssd1306_tests.c runs almost perfectly except for the error in caption. I also not that during the concentric rectangle test, the left hand side of the outermost rectangle is missing which leads me to think that the horizontal counter is getting shifted by a couple of pixels. I get the same result with a second display that I have. However these were bought together from the same supplier on Aliexpress so both could be faulty but I doubt it.

Any suggestions as to where to look for the mistake will be appreciated.

Offset for different OLEDs

Dear afiskon,

I discovered that some displays will have offset in x or y axis. Sometimes the text is shifted left/right or up/down several pixels. I found the solution for this is simple.
In ssd1306.h

/* SSD1309 offset of x in pixels  */
#ifndef SSD1309_OFFSET_X
#define SSD1309_OFFSET_X        -2
#endif

/* SSD1309 offset of y in pixels  */
#ifndef SSD1309_OFFSET_Y
#define SSD1309_OFFSET_Y        0
#endif

In ssd1306.c

void ssd1306_SetCursor(uint8_t x, uint8_t y) {
    SSD1306.CurrentX = x - SSD1309_OFFSET_X ;
    SSD1306.CurrentY = y - SSD1309_OFFSET_Y;
}

Driver fails with 64x32 display

The driver seems to fail with a 0.49" 64x32 Oled display. I verified i2c communication with a protocol analyzer. Certain commands seem to work like 0xAE (display off) 0xAF (display on). I also looked into ssd1306_Init() it seems not to follow the init sequence as specified in the datasheet on page 64 (Figure 2 : Software Initialization Flow Chart) that make problem solving difficult. So I am wondering how 64x32 displays were verified.

For a newbie - STM32 CubeMX IDE - how to use this library in a project

Hi, could you please add an instruction, best practice about how to make use of the ssd1306 library in a project?

1. How to include the library in project workspace
   • can i use git submodule?
   • how to include library .c and .h files in the project - import? link? How to set up project folders, what options to configure in project settings? I dont want to copy files, Twould like to maintain it as an external module that's however built with a project.
   • what configuration is necessary in the IDE (HAL? I2C)
2. How to use the library in the source code
   • what are prerequisites, preprocessor definitions to make
   • how to configure pin numbers
   • where and how to initialize the display
   • how to do it in a portable way (so project can be build for different board)

Thanks, maybe it's obvious but for a newcomer to stm32 ecosystem it's a guessing game. Probably there are well established standard ways of handling external modules.

Edit: i got the library to work by just copying the files into project folders so i think i know how it's supposed to be used from code. And the organization of modules and libraries i think i will figure out later.

Files distributed without permission

These two files contain a license text which disallows distribution in source form, so they should not be included in this repo (or any other):

• examples/oled-tester/firmware/i2c/STM32F411RETx_FLASH.ld
• examples/oled-tester/firmware/spi/STM32F411RETx_FLASH.ld

Testing on STM32L1

Hello, i am tested this library on STM32L1. Function ssd1306_TestAll(); worked successfully.

I am added #elif defined(STM32L1) #include "stm32l1xx_hal.h" in ssd1306.h and #define STM32L1 in ssd1306_conf.h

DMA support

Very nice library! But for practical usability it would greatly benefit from DMA support. Now lots CPU cycles are wasted, but worse the loop in ssd1306_UpdateScreen() burns so much time that introduces much latency in a simple round robin schedule.

Support for STM32WB55 (Nucleo-WB55RG) family

Hello,

it is my first STM32 project and have the Nucleo-WB55RG board.
Would it be possible the you insert the STM32WB family ?

would be great !!

Kind Regards,

stm32f767zi-nucleo board works fine(I2C)

stm32f767zi-nucleo board works fine in I2C(not tested in SPI mode)，just add f7 HAL header file support and define STM32F7.

[Duplicate] font generated question

Hello,
I can run normally with your driver, but now I need to change the ASCII font size, Chinese character set and modify the picture. I would like to ask what software you use for module extraction and generation, could you tell me the specific software and procedures of module extraction? Thank you very much!