ESP32 MicroPython - Écran OLED SSD1309

L'ESP32 est un microcontrôleur puissant, compatible WiFi, largement utilisé dans les projets IoT et embarqués. Associé à MicroPython et à la bibliothèque DIYables OLED SSD1309, vous pouvez facilement ajouter un écran OLED monochromatique net à votre projet.

Ce tutoriel vous guide à travers :

ESP32 MicroPython OLED SSD1309

L'OLED SSD1309

Le SSD1309 est un pilote OLED/PLED CMOS monopuce avec contrôleur pour les systèmes d'affichage graphique à matrice de points à diodes électroluminescentes organiques/polymères. Il se connecte à un microcontrôleur via le protocole I2C (deux fils), rendant le câblage minimal — seules les lignes SDA et SCL sont nécessaires en plus de l'alimentation.

L'afficheur est auto-lumineux (pas de rétroéclairage nécessaire), offre un contraste élevé, un large angle de vue, et est lisible dans des environnements lumineux et sombres. Il est généralement disponible en variantes 128×64 et 128×32 pixels.

Caractéristiques principales :

  • Interface I2C (adresse par défaut 0x3C)
  • Résolution 128×64 pixels (ou 128×32, 96×16, 64×48, 64×32)
  • Défilement matériel intégré en directions horizontale et diagonale
  • Contraste réglable (0–255)
  • Étend framebuf.FrameBuffer — toutes les primitives de dessin MicroPython fonctionnent immédiatement

Description des Broches

Broche Fonction Connexion ESP32
SDA Ligne de données I2C Connecter à GPIO21
SCL Ligne d'horloge I2C Connecter à GPIO22
VCC Alimentation 3,3V à 5V Connecter à 3,3V
GND Masse Connecter à GND
Brochage OLED SSD1309

Câblage

L'ESP32 fonctionne en logique 3,3V, compatible avec l'afficheur SSD1309.

OLED SSD1309 ESP32 Notes
SDA GPIO21 Données I2C
SCL GPIO22 Horloge I2C
VCC 3.3V Alimentation
GND GND Masse
  • Comment connecter l'ESP32 à l'écran OLED SSD1309 128x64 avec une breadboard
Schéma de câblage ESP32 OLED SSD1309 128x64

Cette image a été créée avec Fritzing. Cliquez pour agrandir l'image.

Comment connecter l'ESP32 et l'OLED SSD1309

Cette image a été créée avec Fritzing. Cliquez pour agrandir l'image.

Conseil : Vous pouvez utiliser n'importe quelle broche GPIO capable d'I2C sur l'ESP32. Mettez simplement à jour les valeurs SCL_PIN et SDA_PIN dans le code.

Étapes Rapides

Voici les instructions pour configurer et exécuter votre code MicroPython sur l'ESP32 avec Thonny IDE :

  • Assurez-vous que Thonny IDE est installé sur votre ordinateur.
  • Confirmez que le firmware MicroPython est chargé sur votre carte ESP32.
  • Si c'est la première fois que vous utilisez un ESP32 avec MicroPython, consultez le guide ESP32 - Premiers pas. pour des instructions étape par étape.
  • Connectez la carte ESP32 à l'OLED SSD1309 selon le schéma fourni.
  • Connectez la carte ESP32 à votre ordinateur avec un câble USB.
  • Ouvrez Thonny IDE sur votre ordinateur.
  • Dans Thonny IDE, allez dans Outils Options.
  • Dans l'onglet Interpréteur, choisissez MicroPython (ESP32) dans le menu déroulant.
  • Assurez-vous que le bon port est sélectionné. Thonny IDE le détecte généralement automatiquement, mais vous devrez peut-être le sélectionner manuellement (comme COM3 sur Windows ou /dev/ttyUSB0 sur Linux).
  • Naviguez vers Outils Gérer les packages dans Thonny IDE.
  • Recherchez "DIYables-MicroPython-OLED-SSD1309", puis trouvez la bibliothèque OLED SSD1309 créée par DIYables.
  • Cliquez sur DIYables-MicroPython-OLED-SSD1309, puis cliquez sur le bouton Installer pour installer la bibliothèque.
Bibliothèque ESP32 OLED SSD1309
  • Copiez le code MicroPython fourni et collez-le dans l'éditeur de Thonny.
  • Sauvegardez le code sur votre ESP32 en :
    • Cliquant sur le bouton Enregistrer ou en appuyant sur Ctrl+S.
    • Dans la boîte de dialogue d'enregistrement, choisissez Appareil MicroPython.
    • Nommez le fichier main.py.
  • Cliquez sur le bouton vert Exécuter (ou appuyez sur F5) pour exécuter le script.
  • Observez le résultat — du texte et des graphiques devraient apparaître sur l'écran OLED.

Modèle de Code de Démarrage

from machine import I2C, Pin from DIYables_MicroPython_OLED_SSD1309 import OLED_SSD1309 # Pin configuration — change to match your wiring SCL_PIN = 22 # GPIO22 SDA_PIN = 21 # GPIO21 SCREEN_WIDTH = 128 SCREEN_HEIGHT = 64 SCREEN_ADDRESS = 0x3C i2c = I2C(0, scl=Pin(SCL_PIN), sda=Pin(SDA_PIN), freq=400_000) oled = OLED_SSD1309(SCREEN_WIDTH, SCREEN_HEIGHT, i2c, addr=SCREEN_ADDRESS) # Clear the display, draw something, then push to screen oled.fill(0) oled.text("Hello, World!", 0, 0) oled.show()

Code ESP32 — Hello World

""" Example: Hello World – basic text on SSD1309 OLED Works with: ESP32 Product page: https://diyables.io/products/2.4-inch-oled-display-module-ssd1309-128x64 Wiring guide: ESP32: OLED SSD1309 ESP32 ──────────── ────────── SDA -> GPIO21 SCL -> GPIO22 VCC -> 3.3V GND -> GND """ from machine import I2C, Pin from DIYables_MicroPython_OLED_SSD1309 import OLED_SSD1309 # ── Pin configuration ──────────────────────────────────────────────────────── SCL_PIN = 22 # GPIO22 SDA_PIN = 21 # GPIO21 SCREEN_WIDTH = 128 SCREEN_HEIGHT = 64 SCREEN_ADDRESS = 0x3C # ── Setup ──────────────────────────────────────────────────────────────────── i2c = I2C(0, scl=Pin(SCL_PIN), sda=Pin(SDA_PIN), freq=400_000) oled = OLED_SSD1309(SCREEN_WIDTH, SCREEN_HEIGHT, i2c, addr=SCREEN_ADDRESS) # ── Draw ───────────────────────────────────────────────────────────────────── oled.fill(0) # Line 1 – normal 8×8 font oled.text("Hello, World!", 0, 0) # Line 3 oled.text("DIYables", 0, 16) # Line 4 oled.text("SSD1309 OLED", 0, 32) oled.text("128 x 64", 0, 40) oled.show()

Essayez

  • Câblez l'OLED SSD1309 à l'ESP32 selon le schéma ci-dessus.
  • Téléversez le code avec Thonny IDE.
  • Vous devriez voir "Hello, World!", "DIYables" et "SSD1309 OLED 128 x 64" affichés sur l'écran.

Référence Dessin de Texte

Appel de méthode Ce qu'il fait Notes
oled.fill(0) Effacer tout l'écran (tous les pixels éteints) Toujours appeler avant de dessiner une nouvelle image
oled.text("Hello!", 0, 0) Dessiner du texte à la colonne 0, ligne 0 Police intégrée 8×8 pixels ; 16 caractères par ligne, 8 lignes sur un afficheur 64px
oled.text("Line 2", 0, 16) Dessiner du texte sur la deuxième ligne Les lignes font 8 px de haut ; la ligne suivante est y+8 ou y+16 pour l'espacement
oled.show() Pousser le framebuffer vers l'afficheur physique Rien n'est visible jusqu'à l'appel de show()

Code ESP32 — Dessiner des Formes

""" Example: Draw Shapes – lines, rectangles, and circles on SSD1309 OLED Works with: ESP32 Product page: https://diyables.io/products/2.4-inch-oled-display-module-ssd1309-128x64 Wiring guide: ESP32: OLED SSD1309 ESP32 ──────────── ────────── SDA -> GPIO21 SCL -> GPIO22 VCC -> 3.3V GND -> GND Note: framebuf.FrameBuffer provides: pixel, fill, fill_rect, rect, line, hline, vline, text, blit, scroll, and (on newer MicroPython) ellipse & poly. Circles and triangles require manual drawing or the ellipse/poly helpers. """ from machine import I2C, Pin from DIYables_MicroPython_OLED_SSD1309 import OLED_SSD1309 import time # ── Pin configuration ──────────────────────────────────────────────────────── SCL_PIN = 22 # GPIO22 SDA_PIN = 21 # GPIO21 SCREEN_WIDTH = 128 SCREEN_HEIGHT = 64 SCREEN_ADDRESS = 0x3C # ── Setup ──────────────────────────────────────────────────────────────────── i2c = I2C(0, scl=Pin(SCL_PIN), sda=Pin(SDA_PIN), freq=400_000) oled = OLED_SSD1309(SCREEN_WIDTH, SCREEN_HEIGHT, i2c, addr=SCREEN_ADDRESS) def demo_pixels(): """Scatter individual pixels diagonally.""" oled.fill(0) w, h = SCREEN_WIDTH, SCREEN_HEIGHT for i in range(0, w, 4): oled.pixel(i, i * h // w, 1) oled.show() time.sleep_ms(1500) def demo_lines(): """Fan of lines from the top-left corner. """ oled.fill(0) w, h = SCREEN_WIDTH, SCREEN_HEIGHT for i in range(0, w, 8): oled.line(0, 0, i, h - 1, 1) for i in range(0, h, 8): oled.line(0, 0, w - 1, i, 1) oled.show() time.sleep_ms(1500) def demo_h_v_lines(): """Horizontal and vertical lines.""" oled.fill(0) w, h = SCREEN_WIDTH, SCREEN_HEIGHT # horizontal lines for y in range(0, h, 8): oled.hline(0, y, w, 1) # vertical lines for x in range(0, w, 16): oled.vline(x, 0, h, 1) oled.show() time.sleep_ms(1500) def demo_rectangles(): """Nested rectangle outlines. """ oled.fill(0) w, h = SCREEN_WIDTH, SCREEN_HEIGHT for i in range(0, h // 2, 4): oled.rect(i, i, w - 2 * i, h - 2 * i, 1) oled.show() time.sleep_ms(1500) def demo_filled_rects(): """Alternating filled rectangles.""" oled.fill(0) w, h = SCREEN_WIDTH, SCREEN_HEIGHT for i in range(0, h // 2, 6): color = 1 if (i // 6) % 2 == 0 else 0 oled.fill_rect(i, i, w - 2 * i, h - 2 * i, color) oled.show() time.sleep_ms(1500) def demo_ellipse(): """Ellipses (requires MicroPython 1.20+ for framebuf.ellipse). """ oled.fill(0) cx, cy = SCREEN_WIDTH // 2, SCREEN_HEIGHT // 2 try: for r in range(4, min(cx, cy), 8): oled.ellipse(cx, cy, r, r, 1) # circle outline oled.show() except AttributeError: # ellipse not available; fall back to a manual Bresenham circle _draw_circle(cx, cy, 20, 1) oled.show() time.sleep_ms(1500) def _draw_circle(cx, cy, r, c): """Bresenham circle (fallback when framebuf.ellipse is unavailable).""" x, y, err = r, 0, 1 - r while x >= y: for dx, dy in [(x, y), (y, x), (-y, x), (-x, y), (-x, -y), (-y, -x), (y, -x), (x, -y)]: oled.pixel(cx + dx, cy + dy, c) y += 1 if err < 0: err += 2 * y + 1 else: x -= 1 err += 2 * (y - x) + 1 # ── Main loop ──────────────────────────────────────────────────────────────── while True: demo_pixels() demo_lines() demo_h_v_lines() demo_rectangles() demo_filled_rects() demo_ellipse() """

Essayez

  • Téléversez le code avec Thonny IDE.
  • L'afficheur fait défiler des démonstrations : pixels diagonaux, éventails de lignes, lignes de grille, contours de rectangles et rectangles remplis.

Référence des Méthodes de Dessin

Appel de méthode Ce qu'il dessine Notes
oled.pixel(x, y, 1) Pixel unique en (x, y) 0 = éteint, 1 = allumé
oled.line(x1, y1, x2, y2, 1) Ligne entre deux points Algorithme de Bresenham
oled.hline(x, y, w, 1) Ligne horizontale de largeur w Plus rapide que line() pour l'horizontal
oled.vline(x, y, h, 1) Ligne verticale de hauteur h Plus rapide que line() pour le vertical
oled.rect(x, y, w, h, 1) Contour de rectangle Coin supérieur gauche en (x, y)
oled.fill_rect(x, y, w, h, 1) Rectangle rempli Mêmes paramètres que rect()

Code ESP32 — Faire Défiler du Texte

""" Example: Scroll Text – hardware scrolling on SSD1309 OLED Works with: ESP32 Product page: https://diyables.io/products/2.4-inch-oled-display-module-ssd1309-128x64 Wiring guide: ESP32: OLED SSD1309 ESP32 ──────────── ────────── SDA -> GPIO21 SCL -> GPIO22 VCC -> 3.3V GND -> GND """ from machine import I2C, Pin from DIYables_MicroPython_OLED_SSD1309 import OLED_SSD1309 import time # ── Pin configuration ──────────────────────────────────────────────────────── SCL_PIN = 22 # GPIO22 SDA_PIN = 21 # GPIO21 SCREEN_WIDTH = 128 SCREEN_HEIGHT = 64 SCREEN_ADDRESS = 0x3C # ── Setup ──────────────────────────────────────────────────────────────────── i2c = I2C(0, scl=Pin(SCL_PIN), sda=Pin(SDA_PIN), freq=400_000) oled = OLED_SSD1309(SCREEN_WIDTH, SCREEN_HEIGHT, i2c, addr=SCREEN_ADDRESS) # ── Draw static content ─────────────────────────────────────────────────────── oled.fill(0) oled.text("DIYables", 20, 28) # centred-ish on 128×64 oled.show() time.sleep_ms(2000) # ── Scroll loop ─────────────────────────────────────────────────────────────── while True: # Scroll right across all pages (0–7) oled.scroll_right(0x00, 0x07) time.sleep_ms(3000) oled.stop_scroll() time.sleep_ms(500) # Scroll left oled.scroll_left(0x00, 0x07) time.sleep_ms(3000) oled.stop_scroll() time.sleep_ms(500) # Diagonal scroll right oled.scroll_diag_right(0x00, 0x07) time.sleep_ms(3000) oled.stop_scroll() time.sleep_ms(500) # Diagonal scroll left oled.scroll_diag_left(0x00, 0x07) time.sleep_ms(3000) oled.stop_scroll() time.sleep_ms(500)

Essayez

  • Téléversez le code avec Thonny IDE.
  • L'afficheur défile vers la droite, puis vers la gauche, puis en diagonale droite, puis en diagonale gauche, et recommence.

Référence du Défilement Matériel

Appel de méthode Direction de défilement Notes
oled.scroll_right(0x00, 0x07) Droite Pages 0–7 = toutes les lignes sur un afficheur 64 px
oled.scroll_left(0x00, 0x07) Gauche Pages 0–7 couvre toute la hauteur de l'écran
oled.scroll_diag_right(0x00, 0x07) Diagonale droite (droite + bas) Combine le défilement horizontal et vertical
oled.scroll_diag_left(0x00, 0x07) Diagonale gauche (gauche + bas) Combine le défilement horizontal et vertical
oled.stop_scroll() Arrêter le défilement Appeler avant de dessiner un nouveau contenu

Note : Modifiez le framebuffer (par ex. appelez oled.fill() + oled.show()) avant de démarrer un nouveau défilement pour mettre à jour le contenu. Appelez toujours stop_scroll() avant d'envoyer de nouvelles commandes de dessin.

Code ESP32 — Contraste et Gradation

""" Example: Contrast & Dim – contrast control on SSD1309 OLED Works with: ESP32 Product page: https://diyables.io/products/2.4-inch-oled-display-module-ssd1309-128x64 Wiring guide: ESP32: OLED SSD1309 ESP32 ──────────── ────────── SDA -> GPIO21 SCL -> GPIO22 VCC -> 3.3V GND -> GND """ from machine import I2C, Pin from DIYables_MicroPython_OLED_SSD1309 import OLED_SSD1309 import time # ── Pin configuration ──────────────────────────────────────────────────────── SCL_PIN = 22 # GPIO22 SDA_PIN = 21 # GPIO21 SCREEN_WIDTH = 128 SCREEN_HEIGHT = 64 SCREEN_ADDRESS = 0x3C # ── Setup ──────────────────────────────────────────────────────────────────── i2c = I2C(0, scl=Pin(SCL_PIN), sda=Pin(SDA_PIN), freq=400_000) oled = OLED_SSD1309(SCREEN_WIDTH, SCREEN_HEIGHT, i2c, addr=SCREEN_ADDRESS) # ── Draw a test pattern ─────────────────────────────────────────────────────── oled.fill(0) oled.fill_rect(0, 0, 64, 32, 1) # top-left filled block oled.fill_rect(64, 32, 64, 32, 1) # bottom-right filled block oled.text("Contrast Demo", 8, 28) # label over the blocks oled.show() time.sleep_ms(2000) # ── Contrast / dim loop ─────────────────────────────────────────────────────── while True: # Gradually increase contrast 0 → 255 for c in range(0, 256, 5): oled.set_contrast(c) time.sleep_ms(30) time.sleep_ms(1000) # Gradually decrease contrast 255 → 0 for c in range(255, -1, -5): oled.set_contrast(c) time.sleep_ms(30) time.sleep_ms(1000) # Dim on / off toggle oled.dim(True) time.sleep_ms(2000) oled.dim(False) time.sleep_ms(2000)

Essayez

  • Téléversez le code avec Thonny IDE.
  • Regardez la luminosité de l'afficheur monter et descendre, puis basculer entre la gradation et la pleine luminosité.

Référence Contraste & Gradation

Appel de méthode Effet Notes
oled.set_contrast(0) Luminosité minimale Plage de valeurs 0–255
oled.set_contrast(128) Luminosité moyenne La valeur est sauvegardée en interne pour la gradation/restauration
oled.set_contrast(255) Luminosité maximale La valeur par défaut après init est 0xCF (207)
oled.dim(True) Réduire le contraste à 0 (gradation) Ne modifie pas la valeur de contraste sauvegardée
oled.dim(False) Restaurer le contraste sauvegardé Restaure la valeur définie par set_contrast()
oled.invert(True) Inverser tous les pixels au niveau matériel Pas de changement du framebuffer
oled.invert(False) Restaurer la polarité normale des pixels

Code ESP32 — Bitmap

""" Example: Bitmap – display a monochrome bitmap image on SSD1309 OLED Works with: ESP32 Product page: https://diyables.io/products/2.4-inch-oled-display-module-ssd1309-128x64 Wiring guide: ESP32: OLED SSD1309 ESP32 ──────────── ────────── SDA -> GPIO21 SCL -> GPIO22 VCC -> 3.3V GND -> GND How bitmap drawing works: framebuf.FrameBuffer.blit() copies one FrameBuffer onto another. Bitmap data must be stored row-by-row, MSB first → use framebuf.MONO_HMSB. The blit() call then handles the conversion into the display's MONO_VLSB layout automatically. """ import framebuf from machine import I2C, Pin from DIYables_MicroPython_OLED_SSD1309 import OLED_SSD1309 import time # ── Pin configuration ──────────────────────────────────────────────────────── SCL_PIN = 22 # GPIO22 SDA_PIN = 21 # GPIO21 SCREEN_WIDTH = 128 SCREEN_HEIGHT = 64 SCREEN_ADDRESS = 0x3C # ── Bitmap data – 16 × 16 heart, stored row-by-row MSB first ───────────────── # Each row uses 2 bytes (ceil(16 / 8) = 2). HEART_W = 16 HEART_H = 16 heart_data = bytearray([ 0x00, 0x00, # ................ 0x0C, 0x30, # ....##....##.... 0x1E, 0x78, # ...####..####... 0x3F, 0xFC, # ..############.. 0x7F, 0xFE, # .##############. 0x7F, 0xFE, # .##############. 0xFF, 0xFF, # ################ 0xFF, 0xFF, # ################ 0xFF, 0xFF, # ################ 0x7F, 0xFE, # .##############. 0x3F, 0xFC, # ..############.. 0x1F, 0xF8, # ...##########... 0x0F, 0xF0, # ....########.... 0x07, 0xE0, # .....######..... 0x03, 0xC0, # ......####...... 0x01, 0x80, # .......##....... ]) # ── Setup ──────────────────────────────────────────────────────────────────── i2c = I2C(0, scl=Pin(SCL_PIN), sda=Pin(SDA_PIN), freq=400_000) oled = OLED_SSD1309(SCREEN_WIDTH, SCREEN_HEIGHT, i2c, addr=SCREEN_ADDRESS) # Wrap the raw bytes in a FrameBuffer using MONO_HMSB (row-major, MSB first) heart_fb = framebuf.FrameBuffer(heart_data, HEART_W, HEART_H, framebuf.MONO_HMSB) # ── Draw and animate ────────────────────────────────────────────────────────── while True: # Draw the heart centred on the display x = (SCREEN_WIDTH - HEART_W) // 2 y = (SCREEN_HEIGHT - HEART_H) // 2 oled.fill(0) oled.blit(heart_fb, x, y) oled.text("DIYables", 24, 50) oled.show() time.sleep_ms(800) # Invert colours for a "pulse" effect oled.fill(1) oled.blit(heart_fb, x, y, 1) # key=1 → blit only pixels that are OFF in source oled.show() time.sleep_ms(400)

Essayez

  • Téléversez le code avec Thonny IDE.
  • Une icône cœur 16×16 apparaît au centre de l'afficheur. Elle pulse en alternant les images normale et inversée.

Référence Dessin de Bitmap

Appel de méthode Description Notes
framebuf.FrameBuffer(data, w, h, framebuf.MONO_HMSB) Encapsuler des octets bruts comme un FrameBuffer bitmap Utilisez MONO_HMSB pour les données en ligne-majeur MSB-en-premier
oled.blit(icon_fb, x, y) Copier le bitmap sur le framebuffer d'affichage en (x, y) Tous les pixels sont copiés (pas de transparence)
oled.blit(icon_fb, x, y, 1) Blit avec key=1 — ignorer les pixels avec la valeur 1 Utile pour les effets de style XOR sur des fonds remplis

Référence de la Bibliothèque

Voir la Référence de la Bibliothèque DIYables MicroPython OLED SSD1309 pour la documentation complète de l'API incluant tous les constructeurs, méthodes et constantes.

Prochaines Étapes

  • Combinez avec un capteur DHT11 ou DHT22 pour afficher des lectures de température et d'humidité en temps réel.
  • Ajoutez un bouton pour faire défiler plusieurs écrans d'affichage.
  • Utilisez framebuf.FrameBuffer.blit() pour construire un affichage de sprites animés.

※ NOS MESSAGES

  • N'hésitez pas à partager le lien de ce tutoriel. Cependant, veuillez ne pas utiliser notre contenu sur d'autres sites web. Nous avons investi beaucoup d'efforts et de temps pour créer ce contenu, veuillez respecter notre travail !