04 OLED Screen Control
This tutorial demonstrates how to control an OLED display connected to an ESP32 module using JSON commands. OLED displays are widely used for showing various types of information, such as text and images.
OLED Screens Basics
OLED displays communicate with the ESP32 module via the I2C (Inter-Integrated Circuit) interface. These displays are capable of showing custom text content and support multi-line display.
The product comes with an OLED display that communicates with the ESP32 module through the I2C interface. Upon powering up, the display automatically shows some basic information about the device. The content displayed on the screen can be altered by sending JSON commands from the host device.
OLED Screen Control JSON Commands
- {"T":3,"lineNum":0,"Text":"putYourTextHere"}
- Controls the display to show custom content.
- lineNum refers to the line number, and a single JSON command can change the content of one line. For the commonly used 0.91-inch OLED displays, the value of lineNum can be 0, 1, 2, or 3, allowing for four lines in total.
- Text is the content you wish to display on that line. If the content exceeds the line length, it will automatically wrap to the next line, potentially overwriting the last line's content.
lineNum refers to the line number. A single JSON command can modify the content of one line. When the subordinate machine receives a new command, the default OLED display screen at startup will disappear, replaced by the content you've added. For most products that use a 0.91-inch OLED display, the value of lineNum can be 0, 1, 2, or 3, allowing for a total of four lines. Text is the textual content you wish to display on that line. If the content for a line is too long, it will automatically wrap to the next line, potentially overwriting the content on the last line.
from base_ctrl import BaseController
# Function for Detecting Raspberry Pi
def is_raspberry_pi5():
with open('/proc/cpuinfo', 'r') as file:
for line in file:
if 'Model' in line:
if 'Raspberry Pi 5' in line:
return True
else:
return False
# Determine the GPIO Serial Device Name Based on the Raspberry Pi Model
if is_raspberry_pi5():
base = BaseController('/dev/ttyAMA0', 115200)
else:
base = BaseController('/dev/serial0', 115200)
# Modifying the Display Content on the OLED Screen
base.send_command({"T":3,"lineNum":0,"Text":"this is line0"})
base.send_command({"T":3,"lineNum":1,"Text":"this is line1"})
base.send_command({"T":3,"lineNum":2,"Text":"this is line2"})
base.send_command({"T":3,"lineNum":3,"Text":"this is line3"})
Running the provided code block will display four lines of text on the OLED:
this is line0 this is line1 this is line2 this is line3
Displaying Dynamic Information on OLED
The tutorial above outlined a method for displaying simple text on the OLED screen. We will now proceed with a slightly more complex example. Running the following code block will display the current time on the OLED screen. Note that the time displayed might not be accurate due to potential discrepancies with the Raspberry Pi's clock. This example serves to demonstrate how to update the screen content in the main program, where we employ this method to display real-time information such as the device's IP address and operational status on the OLED screen.
# Import the datetime class from the datetime module to fetch and manipulate the current date and time.
from datetime import datetime
# Import the time module, primarily used for delay processing within the program.
import time
# Create an infinite loop using while True to allow the program to run continuously.
while True:
# Use datetime.now().strftime("%H:%M:%S") to obtain the current time and format it as "hour:minute:second".
current_time = datetime.now().strftime("%H:%M:%S")
# Utilize the base.send_command method to send a command that includes the current time.
base.send_command({"T":3,"lineNum":0,"Text":current_time})
# Use time.sleep(1) to pause the program for 1 second, ensuring that the time is updated and a command is sent every second.
time.sleep(1)
Running the last code block, you'll observe the first line of the OLED screen updating to show the current time, refreshing every second. This function runs in an infinite loop, which can be terminated by clicking the stop button(■) above.