Mastering MicroPython with OLED Displays on Wemos Boards

MicroPython is a lean and efficient implementation of the Python 3 programming language that includes a small subset of the Python standard library and is optimized to run on microcontrollers. Wemos, on the other hand, is a popular line of development boards based on the ESP8266 and ESP32 microcontrollers, known for their low - cost and ease of use. When combined with an OLED (Organic Light - Emitting Diode) display, it becomes a powerful platform for building interactive projects, such as smart sensors, small IoT devices, and educational prototypes. In this blog post, we will explore the fundamentals of using MicroPython with an OLED display on a Wemos board, including basic concepts, usage methods, common practices, and best practices.

Table of Contents#

  1. Fundamental Concepts
  2. Hardware Setup
  3. Software Installation
  4. Usage Methods
  5. Common Practices
  6. Best Practices
  7. Conclusion
  8. References

Fundamental Concepts#

MicroPython#

MicroPython allows you to write Python code directly on microcontrollers, eliminating the need for low - level programming languages like C or C++. It provides a high - level interface to interact with hardware components, which simplifies the development process.

Wemos Boards#

Wemos boards are based on ESP8266 or ESP32 chips. They come with built - in Wi - Fi and Bluetooth capabilities, making them suitable for IoT projects. These boards have multiple GPIO (General - Purpose Input/Output) pins that can be used to connect external devices such as OLED displays.

OLED Displays#

OLED displays are self - emissive, which means they do not require a backlight. They offer high contrast ratios, fast response times, and wide viewing angles. OLED displays typically communicate with the microcontroller using I2C (Inter - Integrated Circuit) or SPI (Serial Peripheral Interface) protocols.

Hardware Setup#

To use an OLED display with a Wemos board, you need the following components:

  • A Wemos board (e.g., Wemos D1 Mini)
  • An OLED display (e.g., 128x64 I2C OLED)
  • Jumper wires

Connection#

  1. Connect the VCC pin of the OLED display to the 3.3V pin on the Wemos board.
  2. Connect the GND pin of the OLED display to the GND pin on the Wemos board.
  3. Connect the SDA (Serial Data) pin of the OLED display to the D2 (GPIO4) pin on the Wemos board.
  4. Connect the SCL (Serial Clock) pin of the OLED display to the D1 (GPIO5) pin on the Wemos board.

Software Installation#

Installing MicroPython on Wemos#

  1. Download the MicroPython firmware for your Wemos board from the official MicroPython website.
  2. Use a tool like esptool.py to flash the firmware onto the Wemos board. Here is an example command:
esptool.py --port /dev/ttyUSB0 erase_flash
esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 esp8266-20230426-v1.20.0.bin

Note: Replace /dev/ttyUSB0 with the actual serial port of your Wemos board and esp8266 - 20230426 - v1.20.0.bin with the downloaded firmware file.

Installing Required Libraries#

We will use the ssd1306 library to control the OLED display. You can copy the library code to the Wemos board using a tool like ampy (Adafruit MicroPython Tool).

ampy -p /dev/ttyUSB0 put ssd1306.py

Usage Methods#

Initializing the OLED Display#

import machine
import ssd1306
 
# Initialize I2C
i2c = machine.I2C(scl=machine.Pin(5), sda=machine.Pin(4))
 
# Initialize OLED display
oled = ssd1306.SSD1306_I2C(128, 64, i2c)
 
# Clear the display
oled.fill(0)
oled.show()

Displaying Text#

# Write text on the display
oled.text('Hello, World!', 0, 0)
oled.show()

Displaying Graphics#

# Draw a line
oled.hline(0, 10, 128, 1)
oled.show()

Common Practices#

Error Handling#

When working with external devices like OLED displays, errors can occur. It is important to handle these errors gracefully.

try:
    i2c = machine.I2C(scl=machine.Pin(5), sda=machine.Pin(4))
    oled = ssd1306.SSD1306_I2C(128, 64, i2c)
    oled.fill(0)
    oled.text('Device initialized', 0, 0)
    oled.show()
except OSError:
    print('Error initializing OLED display')

Display Updating#

To avoid flickering, update the display only when necessary. For example, if you are displaying sensor data, update the display only when the data has changed.

Best Practices#

Code Optimization#

  • Minimize the use of global variables to reduce memory usage.
  • Use functions and classes to organize your code.
class OLEDDisplay:
    def __init__(self):
        self.i2c = machine.I2C(scl=machine.Pin(5), sda=machine.Pin(4))
        self.oled = ssd1306.SSD1306_I2C(128, 64, self.i2c)
 
    def show_text(self, text):
        self.oled.fill(0)
        self.oled.text(text, 0, 0)
        self.oled.show()
 
 
display = OLEDDisplay()
display.show_text('Optimized code')

Power Management#

  • Turn off the OLED display when it is not in use to save power.
# Turn off the display
oled.poweroff()

Conclusion#

Using MicroPython with an OLED display on a Wemos board is a great way to build interactive and lightweight projects. By understanding the fundamental concepts, setting up the hardware correctly, and following the usage methods, common practices, and best practices, you can create efficient and reliable applications. Whether you are a beginner or an experienced developer, this combination offers a powerful and accessible platform for your projects.

References#

2025-10