OLED Screen
Your "Mini TV"
Displaying Text, Images, and Graphics
What it is
The OLED Screen category contains blocks for configuring and controlling an OLED display connected through I2C.
Unlike a simple text display, the OLED blocks allow students to work with:
- Text
- Images
- X and Y coordinates
- Text size and spacing
- Scrolling text
- Frame-based text
- Horizontal and vertical lines
- Free lines
- Hollow and filled rectangles
- Image movement
- Individual pixels
What it does
The OLED Screen blocks allow a program to create a small graphical interface directly on the project.
The display can present sensor values, messages, counters, graphical indicators, shapes, and simple animations.
A typical information flow is:
Sensor → D1 R32 → OLED
The same value can also be observed on the computer:
Sensor → D1 R32 → OLED + Serial Port → PC
Think of the OLED as a small graphical canvas where the program can place text, images, shapes, and individual pixels.
Fun Guide to OLED Display Blocks (Clu-blocks Pro)
What it is: Blocks for more advanced graphic displays.
What it does: Displays graphics and images on advanced screens.
Example: Draw a heart or display large numbers.
It's the robot's artistic display.
Important! OLED blocks let your robot draw pictures, scroll text, and show data on a bright little screen. It’s like giving your robot a digital face or dashboard!
Using the confirmed Clu-Blocks Pro generation, the category can be organized into:
SETUP → IMAGE → TEXT → DRAW → MOVE → PIXELS
Setup & Configuration
| Block | What it does | Dropdown options | What the options mean |
 | Sets up I2C communication | — | Needed before using the OLED SCL/SDA are data pins |
 | Initializes the OLED screen | — | 128x64 is the screen size, SSD1306 is the driver chip |
Display Images and Text
| Block | Block Image | What It Does | Dropdown options | What the Options Mean |
|---|---|---|---|---|
| Display Image |  | Draws an image on the OLED display. | Heart, Angry, Bored, Confused, Happy, Paper, Rock, Sad, Scissors, Silly, Sleep | Heart is the image to display. The image must be available in the program or supported image library. |
| Display Image with Position and Size |  | Draws an image at a specific position and size. | Heart, Angry, Bored, Confused, Happy, Paper, Rock, Sad, Scissors, Silly, Sleep | Heart: image to display. x: horizontal position. y: vertical position. size: image scale; 1 represents the original size. |
| Clear Display Buffer |  | Fills the display buffer with a single color, normally clearing the screen. | 0 turns pixels off (black). On a monochrome OLED, 1 normally turns pixels on. | |
| Display Text |  | Writes text into the OLED display buffer. | The text inside quotation marks is what appears on the screen. | |
| Display Text with Options |  | Displays text with control over its position, size, spacing, and alignment. | True, False | x: horizontal position. y: vertical position. size: text size. space: spacing between characters. center: True centers the text; False disables centering. |
| Display Text Without Centering | Displays text at the specified position without requesting centered alignment. | True, False | x and y: text position. size: text size. space: character spacing. center = False: uses the specified alignment rather than centering. |
Text Animations
| Block | Block Image | What It Does | Dropdown options | What the Options Mean |
|---|---|---|---|---|
| Scroll Text |  | Creates a scrolling text animation on the OLED display. | The text inside quotation marks is the message to animate. | |
| Scroll Text with Options |  | Scrolls text with control over its vertical position, size, speed, and spacing. | y: vertical position. size: text size. speed: scrolling speed. space: spacing between characters. | |
| Frame Text Animation |  | Displays text using a frame-style animation. | The text inside quotation marks is the message to animate. | |
| Frame Text with Options |  | Displays text with a selected size and animation delay. | size: text size. delay: time between animation steps, in milliseconds. 500 means half a second. |
Draw Lines and Shapes
| Block | Block Image | What It Does | Dropdown options | What the Options Mean |
|---|---|---|---|---|
| Draw Vertical Line |  | Draws a vertical line on the display. | hline, vline | First value: horizontal position (x). Second: starting vertical position (y). Third: line height. Fourth: color (1 turns pixels on). |
| Draw Horizontal Line | Draws a horizontal line on the display. | hline, vline | First value: horizontal position (x). Second: vertical position (y). Third: line width. Fourth: color (1 turns pixels on). | |
| Draw Diagonal Line |  | Draws a line between two points on the display. | First two values: starting point (x1, y1). Next two: ending point (x2, y2). Last value: color (1 turns pixels on). | |
| Draw Rectangle Outline |  | Draws the outline of a rectangle. | rect, fill_rect | First value: horizontal position (x). Second: vertical position (y). Third: width. Fourth: height. Fifth: color. |
| Draw Filled Rectangle | oled.fill_rect(20, 20, 20, 15, 1) | Draws a filled rectangle. | rect, fill_rect | First value: horizontal position (x). Second: vertical position (y). Third: width. Fourth: height. Fifth: color. |
Move Display Contents
| Block | Block Image | What It Does | Dropdown options | What the Options Mean |
|---|---|---|---|---|
| Shift Up |  | Moves the existing display contents upward. | UP, DOWN, LEFT, RIGHT | The number indicates the number of pixels to move. |
| Shift Down | oled.shift_down(1) | Moves the existing display contents downward. | UP, DOWN, LEFT, RIGHT | The number indicates the number of pixels to move. |
| Shift Left | oled.shift_left(1) | Moves the existing display contents to the left. | UP, DOWN, LEFT, RIGHT | The number indicates the number of pixels to move. |
| Shift Right | oled.shift_right(1) | Moves the existing display contents to the right. | UP, DOWN, LEFT, RIGHT | The number indicates the number of pixels to move. |
Individual Pixels
| Block | Block Image | What It Does | Dropdown options | What the Options Mean |
|---|---|---|---|---|
| Read Pixel |  | Reads the state of a pixel at a specific position. | First value: horizontal position (x). Second: vertical position (y). The result indicates whether that pixel is on or off. | |
| Set Pixel |  | Turns on a pixel at a specific position in the display buffer. | First value: horizontal position (x). Second: vertical position (y). Third: 1 turns the pixel on. |
Quick Tips for Students
- Use setup blocks first your OLED won’t work witdout I2C and driver setup.
- Use built-in pictures for fun icons like emotions or game symbols.
- Use scroll and frame text for cool effects like typing or marquee.
- Use draw tools to make shapes, borders, or animations.
- Use clear + display control to refresh or hide the screen perfect for transitions.
1. Setting Up I2C
[ INSERT BLOCK IMAGE HERE: I2C Setup ]
The OLED communicates through I2C.
The supplied real generation shows:
Python
i2c_extend = machine.SoftI2C(
scl = machine.Pin(19),
sda = machine.Pin(18),
freq = 100000
)
The important settings are:
| Setting | Purpose |
|---|---|
| SCL | I2C clock connection. |
| SDA | I2C data connection. |
| frequency | I2C communication frequency. |
Conceptually:
D1 R32 ↔ SCL + SDA ↔ OLED
Configure I2C first, then configure the OLED.
2. Setting Up the OLED
[ INSERT BLOCK IMAGE HERE: OLED Setup ]
The confirmed generation creates the OLED using:
Python
oled = oled128x64.OLED(
i2c_extend,
address=0x3c,
font_address=0x3A0000
)
This confirms several important technical details:
- OLED reference:
oled - I2C connection:
i2c_extend - I2C address:
0x3c - Font address generated by the setup:
0x3A0000
All following OLED operations use:
oled
The setup sequence is therefore:
I2C Setup → OLED Setup → Display Content
3. Built-in Pictures
[ INSERT BLOCK IMAGE HERE: Built-in Picture ]
The supplied example contains the built-in image:
Heart
The generated reference is:
Python
Heart
and Clu-Blocks Pro imports the picture with:
Python
from expression_picture import Heart
The picture can then be supplied to an OLED image block.
Conceptually:
Built-in Picture → Display Image → OLED
4. Displaying an Image
[ INSERT BLOCK IMAGE HERE: Display Image ]
The basic image block generates:
Python
oled.image(Heart)
This sends the selected image to the OLED image operation.
The more configurable block generates:
Python
oled.image(Heart, x = 0, y = 0, size = 1)
This introduces three important graphical parameters:
X
Horizontal position.
Y
Vertical position.
Size
Image-size parameter.
The conceptual structure is:
IMAGE + POSITION + SIZE → OLED
5. Clearing the Display
[ INSERT BLOCK IMAGE HERE: Clear Display ]
The actual code generation is:
Python
oled.fill(0)
oled.show()
This reveals an important technical detail.
The first instruction clears the display buffer:
Python
oled.fill(0)
and then:
Python
oled.show()
updates the visible OLED.
For beginners, the block can simply be understood as:
Existing Content → Clear → Empty Screen
6. Displaying Simple Text
[ INSERT BLOCK IMAGE HERE: Display String ]
The basic text operation generates:
Python
oled.shows("Clu-Bots")
Conceptually:
Text → OLED
This should be the first OLED operation students learn.
A simple first program can display:
Clu-Bots
without requiring students to understand coordinates or graphical formatting yet.
7. Positioning and Formatting Text
[ INSERT BLOCK IMAGE HERE: Display String with Options ]
The configurable string block generates operations such as:
Python
oled.shows(
"Clu-Bots",
x = 0,
y = 0,
size = 1,
space = 0,
center = True
)
The actual generation confirms five configurable concepts:
| Parameter | Main Idea |
|---|---|
| x | Horizontal position. |
| y | Vertical position. |
| size | Text-size parameter. |
| space | Text-spacing parameter. |
| middle alignment | Controls the generated center value. |
8. Middle Alignment
We can now document both actual alignment states.
When the block uses middle alignment:
yes
Clu-Blocks Pro generates:
Python
center = True
When middle alignment is:
no
the generator produces:
Python
center = False
So:
| Block Selection | Generated Setting |
|---|---|
| yes | center=True |
| no | center=False |
This is an important improvement over the previous version, where only yes was visible.
9. Understanding X and Y
Coordinates appear throughout the OLED category.
X
Controls the horizontal position.
Y
Controls the vertical position.
So an OLED element can be thought of as:
WHAT? + WHERE?
For example:
Text + x + y
Image + x + y
Pixel + x + y
Rectangle + x + y
This makes coordinates one of the most important concepts in the entire OLED category.
🧠 X tells the program where to move horizontally. Y tells the program where to move vertically.
10. Scrolling Text
[ INSERT BLOCK IMAGE HERE: Scroll String ]
The basic operation generates:
Python
oled.scroll("Clu-Bots")
The configurable version generates:
Python
oled.scroll(
"Clu-Bots",
y = 0,
size = 5,
speed = 5,
space = 0
)
The confirmed parameters are therefore:
- y
- size
- speed
- space
This also gives us an important correction from the previous explanation.
The interface visually describes the timing field as an interval-related setting, but the actual generated function uses:
Python
speed=5
Therefore, the manual should explain the control according to the real generation:
The visible timing/speed field controls the
speedparameter generated for the scroll operation.
11. Showing Text by Frame
[ INSERT BLOCK IMAGE HERE: Show String by Frame ]
The basic form generates:
Python
oled.frame("Clu-Bots")
The configurable form generates:
Python
oled.frame(
"Clu-Bots",
size = 5,
delay = 500
)
The confirmed configurable parameters are:
- size
- delay
This provides another way for the OLED library to present text.
For beginners, scrolling and frame display should be introduced after ordinary text display is understood.
12. Vertical and Horizontal Lines
[ INSERT BLOCK IMAGE HERE: Straight Line ]
The original screenshot visibly showed:
vertical
Now the real generation confirms both orientations.
Vertical
Python
oled.vline(0, 0, 20, 1)
oled.show()
Horizontal
Python
oled.hline(0, 0, 20, 1)
oled.show()
So the selector can be documented accurately:
| Selection | Generated Operation |
|---|---|
| vertical | vline() |
| horizontal | hline() |
The example uses:
- X: 0
- Y: 0
- Length: 20
Conceptually:
Starting Position + Length + Direction → Line
13. Drawing a Line Between Two Points
[ INSERT BLOCK IMAGE HERE: Draw Line ]
The free-line operation generates:
Python
oled.line(0, 0, 50, 50, 1)
oled.show()
The block uses two coordinate pairs:
Starting Point
x1, y1
Ending Point
x2, y2
Conceptually:
Point A → Line → Point B
This is an excellent practical use of X/Y coordinates.
14. Drawing Rectangles
[ INSERT BLOCK IMAGE HERE: Rectangle ]
The original image only allowed us to safely document the visible hollow option.
The real code now confirms two rectangle modes.
Hollow Rectangle
Clu-Blocks Pro generates:
Python
oled.rect(20, 20, 20, 15, 1)
oled.show()
Filled Rectangle
Clu-Blocks Pro generates:
Python
oled.fill_rect(20, 20, 20, 15, 1)
oled.show()
The selector can therefore be documented as:
| Selection | Generated Operation |
|---|---|
| hollow | rect() |
| filled | fill_rect() |
The block combines:
X + Y + Width + Height
This is particularly useful for your existing OLED exercises involving a rectangle that grows and shrinks.
15. Moving the Display Image
[ INSERT BLOCK IMAGE HERE: Image Translation ]
This block was another important area where the original closed selector hid several real operations.
The actual generation confirms four directions.
UP
Python
oled.shift_up(1)
DOWN
Python
oled.shift_down(1)
LEFT
Python
oled.shift_left(1)
RIGHT
Python
oled.shift_right(1)
The complete confirmed selector is therefore:
UP / DOWN / LEFT / RIGHT
The numerical value represents the translation amount supplied to the selected operation.
Conceptually:
Current Display → Direction + Amount → Shifted Display
This introduces students to simple graphical movement.
16. Reading an Individual Pixel
[ INSERT BLOCK IMAGE HERE: Pixel Status ]
The pixel-status block generates:
Python
oled.pixel(0, 0)
The block identifies a pixel using:
x = 0
y = 0
and obtains the value associated with that pixel.
Conceptually:
X + Y → Pixel → Read
The important new idea is that the display can be controlled not only as text or shapes, but at the level of an individual pixel.
17. Turning a Pixel ON
[ INSERT BLOCK IMAGE HERE: Set Pixel ]
The real generation confirms that an individual point can be switched on using:
Python
oled.pixel(0, 0, 1)
oled.show()
The 1 is the generated pixel value for the ON operation.
Conceptually:
X + Y + ON → Pixel Lights
18. Turning a Pixel OFF
The same block can generate:
Python
oled.pixel(0, 0, 0)
oled.show()
The 0 sets the selected pixel to the OFF state.
Therefore:
| Pixel State | Generated Value |
|---|---|
| ON | 1 |
| OFF | 0 |
This resolves the ambiguity we had in the original screenshot.
Why Does oled.show() Appear?
Several graphic operations generate:
Python
oled.show()
after modifying the OLED.
For example:
Python
oled.line(...)
oled.show()
or:
Python
oled.pixel(...)
oled.show()
From the actual generation, students can observe that Clu-Blocks Pro uses show() after several drawing operations to update the visible display.
For the beginner manual, the key concept is simply:
Modify Display → Show Updated Result
Students do not need to manually recreate this behavior when the Clu-Blocks Pro block already generates it.
Text vs. Graphics vs. Pixels
The OLED category becomes easier to understand when students recognize its three levels.
Level 1: Text
Display String
Level 2: Graphics
Images → Lines → Rectangles → Movement
Level 3: Pixels
Read Pixel → Pixel ON/OFF
This gives students a natural progression from basic information display toward elementary computer graphics.
Building a Progress Bar
The confirmed filled-rectangle operation is particularly useful for the OLED exercises you already designed.
Conceptually:
Value
↓
Math / Map
↓
Rectangle Width
↓
Filled Rectangle
↓
Progress Bar
This connects several categories:
Sensor / Variable → Math → OLED
and creates a meaningful visual representation of numerical information.
OLED with Sensors
The OLED becomes especially useful when showing sensor information.
DHT11
Temperature → OLED
Ultrasonic
Distance → OLED
ADXL345
X / Y / Z → OLED
Students can continue using the PC simultaneously:
Sensor → OLED + Serial Port → PC
This reinforces the difference between:
Local Display
and:
PC Monitoring
Quick Guide for Students
Do I want to use the OLED for the first time?
Use:
I2C Setup → OLED Setup
Do I want to display simple text?
Use:
Display String
Do I need to position the text?
Use:
X + Y
Do I need centered text?
Use:
middle alignment = yes
Do I need normal non-centered positioning?
Use:
middle alignment = no
Do I want moving text?
Use:
Scroll String
Do I want a built-in image?
Use:
Built-in Picture → Display Image
Do I need a straight horizontal or vertical line?
Use:
horizontal / vertical line
Do I need a line between arbitrary points?
Use:
x1, y1 → x2, y2
Do I want an outlined rectangle?
Use:
hollow
Do I want a solid rectangle?
Use:
filled
Do I want to move the displayed image?
Use:
UP / DOWN / LEFT / RIGHT
Do I need one specific screen pixel?
Use the Pixel blocks.
Quick Reference
| Family | Confirmed Operations | Main Idea |
|---|---|---|
| Setup | I2C + OLED | Prepare the display. |
| Image | image() | Display a picture. |
| Image Position | x, y, size | Position and size an image. |
| Clear | fill(0) + show() | Clear the screen. |
| Text | shows() | Display text. |
| Text Position | x, y | Position text. |
| Text Format | size, space | Format displayed text. |
| Alignment | center True / False | Enable or disable middle alignment. |
| Scroll | scroll() | Scroll text. |
| Frame | frame() | Use frame-based text presentation. |
| Straight Line | vline() / hline() | Draw vertical or horizontal lines. |
| Free Line | line() | Draw between two points. |
| Rectangle | rect() | Draw a hollow rectangle. |
| Filled Rectangle | fill_rect() | Draw a filled rectangle. |
| Movement | up/down/left/right | Shift the display image. |
| Pixel Read | pixel(x,y) | Read a pixel value. |
| Pixel ON | pixel(x,y,1) | Turn a pixel on. |
| Pixel OFF | pixel(x,y,0) | Turn a pixel off. |