The Color OLED module needs 7 connections to do its job.  GND on the module must be connected to GND on the Activity Board, VCC should be connected to 3.3V, and every other pin (except the one marked N/C - which is an abbreviation for “no connection”), must be connected to an I/O pin.

Pin Connections

The OLED initialize block is used to set up the Color OLED display module. The DIN, CLK, CS, D/C, and RES pins on the module must be matched to the Propeller Activity Board pins they are connected to:

• Plug the Color OLED module into the breadboard. 
• Connect:
  
  • GND on the module to GND on the Propeller Activity Board
  • VCC on the module to 3.3V on the Activity Board
  • DIN on the module to P7 on the Activity Board
  • CLK on the module to P8 on the Activity Board
  • CS on the module to P9 on the Activity Board
  • D/C on the module to P10 on the Activity Board
  • RES on the module to P11 on the Activity Board

Test Program

The test project is the classic "Hello World!" text often used to prove that a communication program is working.

• Make sure that you are logged into BlocklyProp.
• Make sure that the BlocklyProp Client is running.
• Select your board in the device menu.
• Build the program shown below using the COMMUNICATE > OLED blocks: OLED initialize and OLED print text.
• Click in the blue text string block and update the text to say "Hello World!"

• Click the Load RAM & Run button.

The Color OLED will display the information sent to it by the Propeller:

How it Works

The OLED initialize block sets up the connections between numbered Propeller I/O used to connect to each specific signal lines on the OLED display.  The OLED print text block passes the characters in its text string block to the display for rendering.

• If you are stopping now, turn off power to the OLED. Otherwise, you are ready to go to the next page - just follow the link below.

CAUTION: Don’t leave the Color OLED on for long periods of time.  OLEDs can burn out if they are left on and displaying the same image for more than an hour at a time.  Use the OLED command block to “sleep” and “wake” your screen.

Did you Know?

It is possible to use more than one OLED at a time in a project.  The Tiny Tutorial video below uses two displays at once. Something to keep in mind for future projects after going through this tutorial!

When the OLED initialize block is used, it sets up the Propeller microcontroller to communicate with the Color OLED module.  The OLED initialize block installs 1 small font, which allows you to print text and numbers to the OLED module’s screen.  You may want to use a medium or large sized font instead.  In order to use different fonts, you will have to install them into the EEPROM memory on your Activity Board.

Upper EEPROM

The EEPROM memory on the Activity Board and Propeller FLiP can hold up to 64 kilobytes (KB) of data.  The first 32 KB is used to hold your programs when you click “Save to EEPROM”.  The remaining memory — often called upper EEPROM — is used to hold information that can be accessed by the programs you write.

The chart below illustrates how the EEPROM is used.  When you install the Display Fonts, they use about 23 KB of EEPROM memory:

If you look carefully at the chart above, when Fonts are installed, there are about 7.8 kilobytes available for other uses. In BlocklyProp, that area is accessible via the Memory > EEPROM blocks.

Load the Fonts

Installing the fonts does not actually require any circuits, not even the OLED itself.  The program to install the fonts is only a single block.

• Build the program shown above, just using the single COMMUNICATE > OLED > OLED font loader block:
• Click the Load and run (save code to EEEPROM) button.
•  Do not disconnect your board, click any buttons, or press any keys while the fonts are loading. 
• The Terminal window will appear, and the P26/P27 LEDs will begin to blink.  The install process takes about 1 minute to complete. 
• Wait for your Terminal window to say “done” and the P26/P27 LED to turn off before disconnecting or turning off your Activity Board.

Did You Know?

Four Fonts, Three Sizes — The default Sans font style does not need the OLED font loader block.  But once you have loaded the OLED font loader block project to EEPROM, you have the fancy Serif, Script, and Bubble fonts to use. Here are the sizes available to each font:

• Sans: (default) available in small, medium and large
• Serif: medium and large only
• Script: medium and large only
• Bubble: medium and large only

Fixed-width & fixed-height Fonts —  This means that each character takes up the same amount of space.  This makes it much easier to predict where characters will appear on your screen.

The width of each character increases by 6 pixels from small (6 pixels wide) to medium (12 pixels wide) to large (18 pixels wide).  The height increases by 8 pixels from small (8 pixels tall) to medium (16 pixels tall) to large (24 pixels tall).  Because there is a 1 pixel spacer on the right and top of each character, the actual character size is 1 pixel less:

Try This - Change the Font and Size

Now that you have loaded fonts to your Propeller board’s EEPROM, you are ready to experiment with those different fonts and sizes.  By default, the OLED print text block will use the Sans font in size small. You can now change that with the OLED text size block.

• Disable or remove the OLED font loader block.
• Build the program shown below.

• Click the Run once button. The screen will display:

• Change the OLED set text size to large, and then click Run once again. Notice that the text wraps to the beginning of the next line. 
• Add the word "World" back in to the OLED print text block, so it says "Hello World! again, and run it.  If the text does not have enough room at the bottom of the screen, it will wrap back to the top left corner of the screen.
• Keep trying combinations of words, fonts, and sizes until you are familiar with how the different options look together.

Your Turn — Change Color

By default, the OLED print text block will use white text on a black background. The OLED font color block adds another element of fun and functionality!

Add the OLED font color block to your project, just under the OLED set text block.

• Click in the white box in each color block to chose a font color and font background color setting.
• Click Run once to see the effect.
• Try setting both blocks back to white, and run it. What happens?
• Try setting font color to white, and font background color to black. What happens?
• Try different combinations of font and background colors, fonts, and font sizes to see which are easier to read, and which are harder. Make a note of your favorites.

To use the Color OLED module, it is important to understand its coordinate system.  Most computer graphics, displays, and terminals follow a similar convention - the top-left corner is the origin. 

Look carefully at the graphic below.  The display in the graphic shows a single white pixel in each corner of the screen.  The grey text closest to each pixel represents that pixel’s coordinates.  The top-left pixel is in row zero and column zero.  You could also say that it’s x/y position is (0,0).  Since the display is 96 pixels wide, and the first pixel is zero, the rightmost pixel is in column 95.

When we refer to the coordinates of a pixel, we use the notation (x,y), where x is how far across from left to right, and y is how far down from top to bottom.

The cursor is the point where the Color OLED module begins printing text or numbers.  If you set the cursor to (0,0), it will print text beginning at the top-left corner.  If you set the cursor to (2,2), it will begin printing text 2 pixels left and 2 pixels down from the top-left corner:

OLED Coordinates Test Program

This test program prints the Hello World message three times, using different starting coordinates each time.

• Log into BlocklyProp and make a new project for your board.
• Build and save the program shown below:

• Click the Run once button. The Color OLED should display:

How it Works

The program printed Hello World! three times, starting at different coordinates. Since the second and third prints' coordinates were close to the first, the three printings are overlapping. The background, or highlight color, of the text is transparent - you can see though it. 

Did You Know?

What color is transparent? — It depends! 

• If the background color is set to the same color as the font color, the text background will be made transparent.
• If both the font and the background are set to white, the text will be white and the text background will be clear.
• If both the font and the background are set to black, the text will not be visible unless the text is rendered over a shape that is a color other than black.

Try This

If you want your text to cover up what’s underneath it, but you don’t want it to appear highlighted, set the background to match the background of the rest of the screen. 

• Set the font to white and the font background to black.
• Save and run the program. You should see:

To boldly highlight text, set the font and the font background to different colors from the screen.

• Set the font background color to green.
• Save and run the program.

The screen will display:

Your Turn

• Try setting the font and font background to the same bright color.
• Try adding two more OLED font color blocks in your project, so there is one above each OLED set cursor block.  Make each instance of Hello World a different color.
• Experiment with different combinations, and make note of what you like.

The Color OLED module is a great way to display the data received from a sensor, such as the PING))) Ultrasonic Distance Sensor, or sensor or the Memsic Dual-Axis Accelerometer. 

You can use the OLED print number block to send a number value to the Color OLED. This block can hold a number value, or a variable, or any expression that resolves as a number. It can display values as decimal, hexadecimal, or binary numbers.

Example Code - Counting Down

The example project uses a repeat item loop to display a value as it counts down from 100 to 1, updating the display once per second.

• In BlocklykProp Solo, make a new project for your board.
• Build the program shown below:

• Save the program, and then click the Run once button.

Your display should behave like the animated .gif below, which shows the first few iterations of the repeat item loop.  You may notice that right away that something doesn’t look right!

How it Works - and Doesn't!

After initializing the display, the OLED font color block sets the font to white, and the font background to black. This will let each number overwrite the previous number instead of overlapping them.

Next, the loop repeat item from 100 to 0 by 1 sets up our countdown. It starts off by setting the cursor to position 0,0 each time through the loop so each number will display in the upper left corner. The OLED print number block  prints the current value of item each time through the loop. The pause 1000 block slows down the loop so it updates the display once per second.

So what is going wrong? The first time through the loop, item equals 100, and so the program prints “100” to the screen.  Then, on the next trip through the loop when item is reduced by one and it prints “99” to the screen, the last “0” in the original “100” doesn’t get written over. So instead of 99, we see 990, then 980, and so forth.  Eventually it counts down to display 100 again!

Did You Know?

Numbers are text too - From the program above, you can see that the OLED font color block works with the OLED print number block, just the same way it does with the OLED print text block. Likewise, the OLED text size block works with the OLED print number block.  So, as long the extra fonts are installed in uppper EEPROM, you can display your project's sensor values in large purple balloon numbers if that's what you want!

Try This

Now, let's fix the problem in the test code that seems to count down from 100 to 990 to 100 again!  How do you fix this?  Print a few spaces after the number each time you update it.  In fact, a good practice to follow is add enough spaces for your smallest possible number to cover up your largest possible number.

• Add an OLED print text block containing two space characters, just below the OLED print number block:

• Save the project and re-run it.
• Watch it count down. The two extra space characters, printed with the black font background, should now overwrite the leftover numbers as the value printed reduces from 3 digits, to 2 digits, to 1 digit.

Your Turn

Here is a challenge that combines what you have learned so far.

• Save a copy of your Try This project.
• Add the label "Decimal" for the value displayed.
• Expand the code to display the value in hexadecimal and binary, labeled.

The Color OLED module displays shapes as well as text and numbers.  This means that you can create images on the OLED’s screen, and you can use those images for anything you can imagine: art, graphics, icons, math functions, user interfaces - the only limit is your imagination!

Example Program - Random Pixels

The easiest thing to draw is a single pixel!  The following program will draw 100 random pixels.

• In BlocklyProp Solo, make a new project for your board.
• Build the project shown below.

• Save the project, and then click the Run once button.
• Your output should look something like this:

How it Works

The random number blocks provide a random value between 0 and the maximum screen dimension, given by the OLED max height and OLED max width blocks.  These numbers are then used to set the position of the pixel drawn by the OLED draw pixel block.  This then repeats 100 times, drawing 100 different pixels on the Color OLED’s screen. The pause 20 block slows down the process just enough so you can see the pixels appear individually instead of all at once.

Example Program - Drawing Lines

To draw a line, you need to define a start and an end point - the OLED draw line block takes two x/y coordinates:

The following program will draw 10 different lines.

• In BlocklyProp Solo, make a new project for your board.
• Build the project shown below.

• Save the project, and then click the Run once button.
• Your output should look something like this when the program is finished.

Experiment with the program above by drawing lines of different lengths and colors. 

Did You Know?

Taking Shape — In addition to pixels and lines, there are blocks that draw circles and triangles. Each shape has both a color and a fill setting that can be changed, but the shapes themselves are defined differently:

• Rectangles are defined by the coordinates at the top left corner, height, width, and corner roundness.
• Circles are defined by the coordinates at the center of the circle and its radius. 
• Triangles are defined by coordinates for each of their three corners. 

Out of Bounds — Lines and shapes can start “out of frame” where start or end points are outside of the screen’s view.  For example, you could draw a line from (-5,-5) to (150,200) - both points are off-screen.

Try This - Draw a Rectangle

Let's try a program that will draw a rectangle and demonstrate its corner option.  Every second, it will clear the screen and redraw the rectangle with increasing corner roundness.

• In your BlocklyProp account, make a new project for your board.
• Build the project shown below.

• Save the project, and then click the Run once button.
• Your output should start like the image on the left, and then transform to the image on the right.

Notice that initially, the rectangle had no roundness at all (square corners).  By the end of the program, the corners were very rounded.

Your Turn

• Experiment by changing the program above to draw rectangles with different sizes, positions, colors and roundness. 
• Try drawing rectangles that are not filled (outline) by unchecking the “fill” checkbox on the OLED draw rectangle block.
• Try drawing a circle.
• Try drawing a triangle.
• Overlap several different shapes, drawn in different colors. You are making modern art!

Microcontrollers are built using lots and lots of transistors - and transistors are like switches.  Switches can either be off or on.  This means that microcontrollers only understand numbers when they can be written as a series of 1’s and 0’s.  This is called binary.  The Propeller microcontroller stores numbers as a series of 32 1’s and 0’s.  For example, the number 238,472,910 in binary is:

0001110001101101100111011001110

The nice thing about binary numbers is that we can use them to store a few pieces of information in a single number.  In BlocklyProp, color is stored into 24 of the 32 bits.  8 of the bits represent how much red there is, 8 of the bits represent how much green there is, and 8 of the bits represent how much blue there is in a color:

Each 8-bit part of the 32-bit number can hold a value ranging from 0 to 255.

You may have noticed a few blocks in the VALUES menu that refer to color:

You will use some of these blocks to generate different colors for the shapes you will draw on your Color OLED’s screen.

Example Program - RGB Values

This program will use the terminal to ask you for an amount of Red, Green, and Blue and use that information to draw a colored rectangle on the Color OLED’s screen.  You will then be able to use this program to experiment with color and learn how the primary colors (Red, Green, and Blue) colors can be mixed together to create all of the other visible colors.

• In BlocklyProp Solo, make a new project for your board.
• Build the program shown below:

• Save the program, and then click the Run once button.

The Terminal window will appear and ask you to enter three values (one for red, one for green, and one for blue) between 0 and 255.

The program will combine the individual amounts of red, green, and blue into a color value and send it to the Color OLED screen:

You may notice that your screen doesn’t represent the color exactly correctly - the Color OLED module uses very small Red, Green, and Blue LEDs inside each pixel to create a color, and the brightness of the component colors can vary slightly from module to module.  This means that one module might have a slightly reddish tone while another module could have a slightly blueish tone.

Did You Know?

Color Models — This display is using the RGB color model, where red, green, and blue light are mixed to produce many other colors. It is an excellent model for electronic displays that emit light, and its array of three values in the 0-255 range is an easy format to understand.  However, in programming there are other formats for representing color, including Hex and CYMK.  To learn more about the other systems, and to easily convert from RGB to other formats, see https://www.w3schools.com/colors/colors_converter.asp [5].

Try This

The next program will use the repeat item block to set the color (and position) of a rectangle.

• In BlocklyProp Solo, make a new project for your board.
• Build the program shown below:

• Save the program, and then click the Run once button.

The Color OLED should display:

Your Turn

Instead of drawing a rectangle, try drawing lines to create a gradient - an area that transitions from one color to another:

Animation means “lively” - and when we can make a shape on the screen move, it makes it appear alive.  You can animate a shape or drawing by drawing it, erasing it, and redrawing it in a new position - if you do this enough times quickly enough, you create the appearance of movement.

Example Program - Moving Rectangle

• In  BlocklyProp Solo, make a new project for your board.
• Build the program shown below:

• Save the program, and then click the Run once button.

Your screen should show a white box slowly moving from left to right across the Color OLED’s screen:

• Try making the block move faster by decreasing the pause value.

How it works

This example program draws a white rectangle, waits 1/10th of a second, draws a black rectangle to erase it, and draws a new white rectangle 1 pixel to the right of the original, and then repeats the process.  This process makes the white rectangle appear to move across the screen.

Did You Know?

How fast can you see? — It takes your eyes about 1/15th of a second to make out an image - this means that if the image changes slightly every 1/15th of a second, the images will blend together and appear to our brains as if the image is moving.  Movies and TV show your eyes a new still image 25 to 30 times each second.  Some computer screens refresh their screens up to 120 times each second. This refresh rate may be called the frame rate, labeled fps for frames per second.

Try This

There are two techniques that can be used to make a computerized animation seem even more realistic: begin your animation "off screen" and only "erase" what you have to.  Let's try the first technique.

Did you notice that the full rectangle started at left edge, but disappeared into the right edge of the screen? To start it off-screen from the right edge, just start the repeat item value with a negative number small enough to "hide" the pixel width of the shape. It's a 10 x 10 square, so we'll use  -10.

• Make the following change to the Moving Rectangle example program above:

• Save and run the modified program.

Now, the first rectangle is "drawn" completely off-screen.  When the animation begins, it will move one to the screen one pixel-column at a time, giving a more naturally appearing motion.

Your Turn

You may have noticed that in each loop, the entire rectangle is erased and redrawn.  Instead of erasing the whole rectangle each time, you may only have to erase a small part of it - this results in a smoother looking animation:

• Modify the code again so it only erases what is necessary each time through the loop. It's easier than it may seem - just replace the second OLED draw rectangle block with the OLED draw line block shown below:

So far, this tutorial has shown how to print text and draw shapes directly on the OLED display with a series of blocks.  You can also display bitmap images stored on  an SD card. This is easy if you are using the Propeller Activity Board WX, which has a microSD card slot built in.

Bitmap Pictures

First, you will need a tiny bitmap image! Such images could start as a photograph you take, or as digital artwork you create in other software.  The example below started out as a 3.5 x 5 foot (about 1 x 1.5 meter) acrylic painting that was photographed and then reduced. Here are some tips:

• Make an image that is 96 x 64 pixels or smaller.
• To reduce a very large image down that small, reduce it by 50% several times until it is about the right size, then make the final adjustments.
• Save the image in the .BMP format.  Paint, Snagit, and Inkscape are examples of programs that can save images as .BMP files.
• Or, just right-click and download/save sun.bmp shown below, which is used in these example projects.

Example - Display Bitmap

• Give your BMP file a name with 8 characters or fewer. (If you don't have one, you can right-click and save the example, sun.bmp, above.)
• Load the BMP file onto a FAT32-formatted microSD card, such as Parallax #32328 [6].
• Once the BMP file is loaded, insert the card into your Activity Board's micro SD card slot, and place the power switch to position 1.
• Build the block program below. Use your .BMP file name in the place of "sun." Notice that the OLED draw BMP image block does not require the .bmp extension, only the name of the file.

• Save and download the block program onto your board by clicking the Run once button.

Keep in mind that the OLED is slow to update and will take approximately 20 seconds to fully display an image.

Try This: Picture Position

• Try changing the coordinate values (x) and (y) in the OLED draw BMP image block, and re-run the project.

What is the outcome on the screen?

• From the dropdown menu on the OLED command block, change the pin orientation to left, right, or down, and re-run the project.

Now what is the outcome on the screen?

• Try experimenting with changing the coordinates and pin orientation at the same time.

Displaying BMP Image and Playing a WAV file

If you want to enhance your OLED projects with audio, there are a few things to take into account.   The OLED draw image block and the WAV play block both access files stored on your Activity Board’s SD card. The OLED draw image block lets go of the SD card after fetching the .BMP file, but the WAV play block keeps ahold of the SD card for itself until your file is done playing or you release it with a WAV stop block.

You will need a .WAV file for this next example project. See our Sound Library [7] to download a properly-formatted WAV file. Or, follow the directions there to create or reformat your own.   This example project uses bird.wav.

bird.wav [8]

Example - Sound and Picture

• Add a WAV file to your SD card, and put it back in the Activity Board's SD card slot. 
• Plug in earbuds or this Hamburger Style speaker (#900-00018) [9] to the Activity Board’s audio jack.
• Update your project with the WAV blocks and pause block shown below:

• Enter your file name into the OLED draw BMP image block, do the same for the WAV play block. Remember, no file extensions! (This example uses sun.bmp and bird.wav)
• Adjust the pause block to match the length of time you expect your WAV file to play. (The bird.wav file lasts 10 seconds, 10000 ms.)
• Adjust the WAV volume block to the desired volume from one to ten.
• Save the project then click the Run once button to download it onto your board.

You should see the image fill the OLED display, then hear the WAV file playing.

Your Turn

• Try moving just the WAV play block to the top of the project, then re-run it. Does the bitmap image ever display? Why or why not?
• Try moving all of the OLED blocks below the WAV stop block, then re-run the project. Does the bitmap image ever display?
• Now, try disabling the WAV stop block, and changing the pause to 5000 ms. Re-run the project. Does the bitmap image ever display?
• Change the pause to 12000 ms. Does the bitmap image display now?