Sporting only a 5x5 LED display panel, micro:bit's display capabilities are very rudimentary when large amounts of data needs to be displayed. Monochrome OLED displays come in two sizes: 0.96in and 2.42in and they are based on the SDD1306 and SDD1309 chips respectively. These displays provide 128x64 monochrome panels with plenty of real-estate. They also support both I2C and SPI connectivity. Please note that there are various single color versions of these displays, providing pixels colors of white, blue, yellow, orange, green.
OLED Graphics library consists of a set of services, that together simplify the use of the OLED displays. It is 100% written in MicroBlocks and all the code of the provided library blocks can be examined by right clicking the blocks and selecting show block definition.
For a more technical and detailed specifications and operational characteristics of the displays, as well as how to connect these displays to your specific micro controller, please refer to the Transfer IMAGE and CodeBlocks from SNAP to MicroBlocks project located in the SNAP! section of the Tutorials on the main WIKI page.
Due to the memory requirements, this library does not work with micro:bit v1.
The OLED library provides support for:
For each block, there is a short description entry and a detailed block description. You can click on block pictures in the short description table to access the details.
Due to the large number of blocks, we have provided a download link for an OLED Demo Program that can be used to check out the operations of the individual blocks. This will provide more in context use cases for the blocks. You are still free to experiment by simply clicking on the blocks in the IDE environment, provided you have initialized the specific connectivity you are using to attach your display to the microcontroller.
Download the OLED Demo Program to see examples of how to use the library blocks.
OLED Library has two distinct types of block shapes:
oval: these are reporter blocks that return some kind of information back. The user would normally either assign these to a project variable or use it in a suitable input slot of other blocks.
rectangular: these are command blocks that perform a programmed function and do not return any information.
In all the blocks described below, x value range is 0-127 and y value range is 0 - 63.
Used to initialize the i2c mode of operation.
One can select one of the two types of displays supported in the first dropdown menu.
Default address is 3C and can be changed if needed.
The flip control is used to adjust the display top position. Normal orientation is with the cable connections on the LEFT side of the display. However, if one needs to use the display such that the cables are on the RIGHT side of the display, then setting this field to TRUE will flip the top position and show everything in the correct orientation.
Used to initialize the i2c mode of operation.
One can select one of the two types of displays supported in the first dropdown menu.
d/c pin# sets the pin that will be used to control data or command transmissions to the display.
reset pin# is used to programmatically reset the displays.
The flip control is used to adjust the display top position. See above.
This block displays the text input at the given display coordinates. Top left corner is x=0, y=0.
inverse option, when set to TRUE, displays the text in inverse video, black text pixels on an inverse monocolor background.
If the length of the text is larger than the available space on a display line, it will wrap to the position of column x. This behavior was selected to facilitate the display of columnar info.
This block allows one to exercise control over the display of the virtual graphics buffer.
Normally, every display operation will automatically transfer the buffer contents to the physical display. This makes it easy to use the library blocks.
However, in some instances it is desirable not to update the display at every step of the buffer build-up, and defer display updates block can be used to delay the updates. When the buffer build-up is completed and display is required, show display buffer block can be used to transfer the buffer contents to the OLED display.
Clears the display contents as well as the contents of the virtual display buffer.
There is another "advanced" _clear display block that can be used to just clear the display without clearing the virtual display buffer. This can be useful when programming animations.
OLED display hardware supports brightness levels in the range of 1-255. However, not all the levels result in substantially visible brightness levels. We have provided this control which simplifies the brightness controls to four settings.
Displays a circle of radius n with the center located at the x and y coordinates. One can generate circles larger than the display boundaries.
The erase control, when set to TRUE, allows one to erase the last drawn circle.
This block will display an image byteArray at the given coordinates.
Image byteArrays can be as simple as a character, or a sprite generated using the make image block, or programmatically generated images of any size to fit within the boundaries of the display.
For an example of handling large size images, as well as the technical details of the image format and display, take a look at the Transfer IMAGE and CodeBlocks from SNAP to MicroBlocks project located in the SNAP! section of the Tutorials on the main WIKI page. Using this example program, one can generate and transfer image byteArrays to the MicroBlocks programs and display them using this block.
There are three library variables that are used by this block, and control the display operations:
_imgHeight: specifies the height of the image in pixels
_imgWidth: specifies the width of the image in pixels
_imgData: is a byteArray representing the pixels of the image.
This block is used to draw lines on the display.
Lines are defined by starting and ending x,y coordinates.
Line thickness is always a single pixel.
erase control can be used to erase the last drawn line.
This block is used to draw rectangles on the display.
Rectangles are defined by a x,y coordinate of the top left corner and a width and a height specification. Line thickness is always a single pixel.
erase control can be used to erase the last drawn rectangle.
rounding control allows one to specify rounded corners for the rectangles.
This block is used to draw filled rectangles on the display.
Rectangles are defined by a x,y coordinate of the top left corner and a width and a height specification. Line thickness is always a single pixel.
erase control can be used to erase the last drawn rectangle.
This is a reporter block mainly used to generate simple 5x5 sprites. This block can be placed directly into the draw image block described earlier and used to display sprites on the display.
eg: the sprite shown on the block will generate a byteArray with values (31, 17, 21, 17, 31).
The byteArray format is simple binary number of five bits, with the least significant bit located at the top
As a result, library variables _imgWidth and _imgHeight will be set to 5, and the _imgData will be set to the byteArray values of the generated image.
Different make image block results can be assigned to variables to store many different sprite images in a given program. These then can be used for animations in game programming. Check out the animated Sprites example in the OLED Demo Program.
Individual pixels of the display can be turned on and off using this block. This feature can form the basic blocks of creating drawings, text characters, or sprites.
The display can be put into an inverse video mode by use of this block. The entire display will shown with black pixels displayed on top of a colored background.
The inverse background color will depend on the type of display one has purchased. There are displays with yellow, orange, green, blue, white pixel colors.
Normal display operation can be restored by selecting normal in the dropdown menu.
This block returns the x and y coordinates of the last pixel location as a byteArray.
This block is used to delay the display of virtual graphic buffer contents, to facilitate complex image build-ups. Once the display image is composed, the complementary block show display buffer can be used to display it.
Normal display orientation is with the cable connections on the LEFT side of the display. However, if one needs to use the display such that the cables are on the RIGHT side of the display, then using this block will flip the top position and show everything in the correct orientation.
This block is used internally to achieve this flipping if any of the blocks with flip option have been set to TRUE.
This block turns off the display of the buffer content and instead displays a full screen of inverse video, all pixels set to on. It can be used to quickly verify if all the pixels of the display are operational. It will not destroy the buffer contents at the time this block is executed.
If the display of the buffer content was turned off using the block above, then this block resumes the display of the buffer content. Whatever was displayed on the screen previously will be restored.
This block is used to reset the cursor related controls to their initial values.
Sets display hardware bounds to full range and resets cursor location to the origin top-left (0,0).
Rows: 0-7
Cols: 0-127
_textX and _textY cursor positions are reset to 0.
Cursor position is affected by any display operation.
Used to turn on/off the display hardware. When the OFF option is used, the display goes into a SLEEP mode and uses very little power. The buffer contents displayed will not be lost while the display is OFF.
The ON mode fully powers on the display and restores the display of the buffer contents exactly as it was before.
Some display models require the use of a designated reset pin# to enable programmatic control of the hardware reset. Any free and available digital pin# can be used.
The SPI mode of operation of the display requires that a data / command write control is issued prior to sending these two types of command details. This block is used internally to notify the display that what is following is a command.
The SPI mode of operation of the display requires that a data / command write control is issued prior to sending these two types of command details. This block is used internally to notify the display that what is following is a display data.
These three blocks (_T1, _T2, _T3) control the character generation matrices for the 8x8 font used to display text on the display. They convert the hexadecimal character display codes to decimal byteArray format and populate the _cDecTBL variable to store them. Each character that needs to be displayed then accesses this data and places it to the display buffer to be displayed.
See block above.
See block above.
This block is the lookup function that converts a character to its byteArray codes and returns the specific values.
InvYN setting controls the inverse video setting of the text displayed. If it is set to TRUE, the character control codes are modified by an XOR operation to produce the inverse video codes.
There are times when one needs to clear the display without destroying the virtual display buffer content. This technique is used when programming sprite animations or various text effects. At the conclusion of this block's execution, the display is cleared, but the display buffer content is not touched, and can be further manipulated to achieve the effects desired.
Drawing rectangles provides an option to use rounded corners. If this option is selected, this block is used internally to draw the pixels of the rounded corners.
First parameter is the corner to be rounded, represented by one of four values:
TL: top left,
TR: top right,
BL: bottom left,
BR: bottom right.
Second and third parameters are the x and y coordinates of the center point of the circle segment to be drawn.
Fourth parameter is the radius of the circle segment that will make up the rounded corner.
Since this block is used only internally, there are no parameter names present on the block.
This block is used to convert decimal numbers to hex using a fast table-lookup algorithm. It returns a modula four digit hex number. It is used mainly internally.
Creates the character set used in the Library (96 characters) and stores them in the variable _cTABLE.
For each character, _cDecTbl is updated with 8 byteArray values.
It is mainly used internally during the initialization process.
Verifies that the library is initialized before the blocks are used.
Sets the display hardware timings and operational parameters for each display type.
It is the most crucial block in the library and should NOT BE MODIFIED unless one understands the hardware operational details described in the SDD1306 and SDD1309 Reference Guides.
Sets all library variables and initializes the display hardware.
It also initializes the virtual display buffer, and clears the display.
Processes the new uniform hex image data format shared between all operations to display characters, sprites, and images. It converts the hexadecimal image data strings to decimal byteArray format. It also sets the _imgWidth and _imgHeight values according to the image dimensions.
It is used internally.
This is a wrapper block to send commands to the displays for any connection type used. Input is a comma separeted hexadecimal command string.
This is a block that verifies x coordinate values for range 0-127 and y coordinate values for range 0-63.
It is used internally.