A Complete Guide to 1.3-Inch OLED Display Code Development: From Fundamentals to Practical Applications

In the fields of embedded systems, smart wearable devices, and IoT terminals, small-sized displays serve as the core medium for human-computer interaction. The 1.3-inch OLED (Organic Light-Emitting Diode) display, with its high contrast, low power consumption, and compact, lightweight design, has become the preferred display solution for numerous small electronic devices. Unlike traditional LCD displays, OLEDs do not require a backlight module—each pixel emits light independently, enabling pure black rendering and vibrant colors. This makes them particularly suitable for scenarios where display quality and power efficiency are critical, such as smart bracelets, microcontroller debugging panels, and portable sensor terminals.

However, to fully unleash the performance of a 1.3-inch OLED display, code development is a crucial step. Whether it involves driving the display to light up, showing text and images, optimizing display efficiency, or reducing power consumption, precise code implementation is essential. This article will start from technical principles, combine mainstream development platforms (such as Arduino, STM32, and Raspberry Pi), and detailedly explain the code development process, core technical points, and solutions to common problems for 1.3-inch OLED displays. It will also provide practical cases and optimization suggestions to help developers quickly master the entire process from "hardware connection" to "code implementation", while offering comprehensive technical reference content for Google SEO users.

Before writing code, it is necessary to clarify the core parameters of the display, as these parameters directly determine the code's driving logic, data transmission method, and display effect configuration.

1. Resolution: The mainstream resolution of 1.3-inch OLED displays is 128×64 (with some models featuring 128×32), meaning 128 pixels horizontally and 64 pixels vertically. Resolution determines the size of the "display buffer" in the code. For example, a 128×64 resolution display requires a buffer of 128×64/8 = 1024 bytes when each pixel is represented by 1 bit of data. This parameter directly affects the definition of arrays and memory allocation in the code.
2. Interface Type: Common interfaces include I2C (two-wire, SDA/SCL) and SPI (four-wire/five-wire, SCLK/MOSI/CS/DC/RST). The interface type determines the choice of "communication protocol" in the code. For I2C interfaces, the code needs to configure the I2C address (e.g., 0x3C or 0x3D) and send commands and data through I2C functions. For SPI interfaces, the code must control the voltage levels of the CS (chip select), DC (data/command selection) pins, and achieve high-speed data transmission via the SPI bus.
3. Driver Chip: The mainstream driver chip is SSD1306 (suitable for 128×64 resolution), while some displays use SH1106 (which offers broader compatibility and supports different resolutions). The driver chip determines the "command set" in the code. For instance, when initializing the display, commands such as "set display contrast", "turn on display", and "set memory address mode" need to be sent to the SSD1306. Different chips have different command codes, so the code must be adapted accordingly.
4. Display Color: Most 1.3-inch OLED displays are monochrome (e.g., black-and-white, blue-and-white), while some are dual-color (e.g., blue-and-yellow). The color type affects the "pixel data encoding method" in the code. Monochrome displays use 1 bit of data to represent each pixel (0 = off, 1 = on), while dual-color displays require 2 bits to distinguish colors (e.g., 00 = off, 01 = blue, 10 = yellow).

For example, if using a 1.3-inch OLED display with "128×64 resolution, I2C interface, and SSD1306 driver chip", the code must meet three core requirements: ① Define a 1024-byte display buffer array; ② Configure I2C communication parameters (address, speed); ③ Call the initialization command set of the SSD1306. A parameter mismatch (e.g., using SPI interface code to drive an I2C display) will directly cause the display to be unresponsive, which is one of the most common issues for novice developers.

The environment configuration varies across different development platforms. Below, we will explain the basic environment setup process using mainstream platforms such as Arduino, STM32, and Raspberry Pi.

• Hardware Preparation: Arduino Uno/Nano development board, 1.3-inch OLED display (I2C/SPI interface), jumper wires, USB data cable.
• Software Installation:

1. Download and install the Arduino IDE (official website: https://www.arduino.cc/);
2. Install OLED driver libraries: Open the IDE, click "Sketch" → "Include Library" → "Manage Libraries" in sequence. Search for "Adafruit SSD1306" and "Adafruit GFX" (a graphics library that supports text and graphics drawing), then click "Install";
3. Hardware Connection: For the I2C interface, connect the display's SDA to Arduino's A4 pin and SCL to A5 pin (based on Uno/Nano pin definitions). For the SPI interface, connect SCLK to pin 13, MOSI to pin 11, CS to pin 10, DC to pin 9, and RST to pin 8.

• Hardware Preparation: STM32F103C8T6 minimum system board, 1.3-inch OLED display, USB-to-serial module.
• Software Installation:

1. Install Keil MDK-ARM (requires license registration) or STM32CubeIDE (open-source and free);
2. Configure peripheral drivers: Use STM32CubeMX to generate initialization code, enable I2C/SPI peripherals, and configure GPIO pins (e.g., set CS/DC/RST pins as push-pull outputs);
3. Port OLED driver code: Add SSD1306 driver functions (such as OLED_Init, OLED_Clear) to the project and associate them with underlying I2C/SPI functions (e.g., HAL_I2C_Master_Transmit).

• Hardware Preparation: Raspberry Pi 4B/Zero, 1.3-inch OLED display (I2C interface), Micro USB power supply.
• Software Configuration:

1. Enable the I2C interface: Use the "raspi-config" tool, enable I2C in "Interface Options", and restart the Raspberry Pi;
2. Install dependent libraries: Open the terminal and execute sudo apt-get install python3-smbus python3-rpi.gpio to install the I2C communication library;
3. Download OLED driver code: Obtain the Python version of the SSD1306 driver library (e.g., adafruit/Adafruit_CircuitPython_SSD1306) from GitHub, extract it, and import it into the project.

1. Display Initialization Principle: After power-on, the OLED display requires the code to send initialization commands to complete operations such as "display mode configuration", "contrast adjustment", and "memory clearing". Taking the SSD1306 chip as an example, the initialization command process is as follows:

• Turn off the display (command 0xAE): Prevents garbled characters from appearing during initialization;
• Set display clock division (command 0xD5 + parameter 0x80): Configures the display refresh rate;
• Set multiplex ratio (command 0xA8 + parameter 0x3F): Selects 64-line driving for 128×64 resolution;
• Set display offset (command 0xD3 + parameter 0x00): Adjusts the display position offset;
• Set start line (command 0x40): Starts display from the top of the screen;
• Set segment re-mapping (commands 0xA0/0xA1): Selects the horizontal display direction of pixels (0xA0 = normal, 0xA1 = inverted);
• Set COM scan direction (commands 0xC0/0xC8): Selects the vertical display direction of pixels (0xC0 = normal, 0xC8 = inverted);
• Set COM pin configuration (command 0xDA + parameter 0x12): Adapts to the display's hardware design;
• Set contrast (command 0x81 + parameter 0xCF): A higher value results in a brighter display (adjustable between 0x00 and 0xFF);
• Turn off entire display on (command 0xA4, command 0xAF turns it on): Selects the "pixel-independent lighting" mode;
• Set display mode (command 0x20 + parameter 0x00): Selects the memory address mode (horizontal address mode, vertical address mode, page address mode);
• Turn on the display (command 0xAF): Completes initialization, and the display enters the standby state.

1. Data Transmission Principle: The code sends "commands" and "data" to the OLED display through the interface (I2C/SPI). The difference between the two is distinguished by pin voltage levels or data frame formats:

• I2C Interface: Before sending data, a "control byte" must be sent. If the control byte is 0x00, it indicates that subsequent data are commands; if it is 0x40, it indicates that subsequent data are display data. For example, when sending a "clear screen" command via I2C, the code logic is: first send the I2C address (0x3C), then send the control byte (0x00), and finally send the clear command (e.g., 0x2E).
• SPI Interface: The DC pin is used to distinguish between commands and data. When DC = 0, commands are sent; when DC = 1, data are sent. For example, before sending display data, the CS pin must be pulled low (to select the display), the DC pin pulled low (to indicate a command), the "set memory page address" command sent, the DC pin pulled high (to indicate data), the pixel data sent, and finally the CS pin pulled high (to end transmission).

1. Display Buffer Principle: To avoid screen flickering, the code usually adopts a "display buffer" mechanism. First, a complete display image (such as pixel data for text and graphics) is constructed in memory, and then the buffer data are sent to the OLED display's memory at once. Taking a 128×64 resolution I2C display as an example, the buffer is a 1024-byte array (buf[1024]), where each byte corresponds to 8 vertical pixels on the display (e.g., buf[0] corresponds to 8 pixels in the first column of the first page). When drawing text or graphics in the code, the essence is to modify the corresponding bits of the buffer array, and then write the buffer data to the display memory via I2C/SPI.

// Include driver libraries#include <Adafruit_GFX.h>#include <Adafruit_SSD1306.h>// Define display resolution (128×64)#define SCREEN_WIDTH 128#define SCREEN_HEIGHT 64// Initialize OLED display with I2C interface (SDA/SCL are default pins)Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);// Chinese dot matrix data (taking "1.3英寸OLED" as an example, 16×16 dot matrix)const unsigned char chinese[6][32] = {  // Character "1" (16×16)  {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xFF,0xFF},  {0xFF,0xFF,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00},  // Character "." (16×16)  {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00},  {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xFF,0xFF},  // Character "3" (16×16)  {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xFF,0xFF,0xFF,0xFF},  {0xFF,0xFF,0xFF,0xFF,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00},  // Character "英" (16×16, omitted here, replace with actual dot matrix data)  {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00},  {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00},  // Character "寸" (16×16, omitted here)  {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00},  {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00},  // Character "OLED" (16×16, omitted here)  {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00},  {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}};// Custom function to display Chinese charactersvoid displayChinese(int x, int y, int index) {  for (int i = 0; i < 16; i++) {    unsigned char data1 = chinese</doubaocanvas>