The 296x128 2.9 inch ePaper Display Module (#28084) is easy to add to your BlocklyProp projects. It can be used for displaying graphics, text, and images. The display portion of the ePaper module measures 2.9" diagonal, and contains 296 x 128 pixels. Each pixel can display black or white.
This tutorial shows you how to connect the ePaper Display Module to your Propeller Activity Board. Then, it will guide you through writing BlocklyProp programs to display text, numbers, and images on your ePaper display. It covers using different fonts and drawing different shapes on a black or white display.
*Any other Propeller development board with a similar 5 MHz oscillator and 64 KB EEPROM will likely work with this tutorial.
The ePaper module needs 8 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 all remaining pins must be connected to an I/O pin on Propeller Activity Board.
The ePaper initialize block is used to set up the ePaper display module. The DIN, CLK, CS, DC, RES and BUSY pins on the module must be matched to the Propeller Activity Board pins they are assigned to:
The test project is the classic "Hello World!" text often used to prove that a communication program is working.
The ePaper will display the information sent to it by the Propeller:
The ePaper initialize block sets up the connections between numbered Propeller I/O pins used to connect to each specific signal line on the ePaper display. The ePaper print text block passes the characters in its text block over to the display and the ePaper update block updates the screen.
CAUTION: Don’t leave the ePaper on for long periods of time. The ePaper can be damaged if left powered on and displaying the same image for more than 24 hours at a time. Use the ePaper command block to “sleep” and “wake” your screen. The ePaper cannot be refreshed directly under sun light. The refresh steps should be done indoors.
When the ePaper initialize block is used, it sets up the Propeller microcontroller to communicate with the ePaper module. The ePaper initialize block installs 1 small font, which allows you to print text and numbers to the ePaper 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.
The EEPROM memory on the Activity Board 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 for your Activity Board.
The chart below illustrates how the EEPROM is used. When you install the ePaper fonts, they use about 23 KB of EEPROM memory:
If you look carefully at the example chart above (though your program may not have ActivityBot calibration data in the EEPROM), 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.
Installing the ePaper fonts does not actually require any circuits, not even the ePaper module itself. The program to install ePaper fonts is only a single block.
Four Fonts, Three Sizes — The default Sans font style does not need the ePaper font loader block. But once you have loaded the ePaper 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:
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:
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 ePaper print text block will use the Sans font in size small however you have other font and size options.
2.9" ePaper Font Display - Sans Blockly Code Example [7]
2.9" ePaper Font Display - Serif Blockly Code Example [8]
2.9" ePaper Font Display - Script Blockly Code Example [9]
2.9" ePaper Font Display - Bubble Blockly Code Example [10]
By default, the ePaper print text block will use black text on a white background. The ePaper font color block adds another element of fun and functionality!
To use the ePaper 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 black 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 its x/y position is (0,0). Since the display is 128 pixels wide, and the first pixel is zero, the rightmost pixel is in column 127.
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 ePaper 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:
This test program prints the Hello World message three times, using different starting coordinates each time.
The program prints 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 and look like they blend together.
What happens when different combinations of font and background color are written close to each other? — It depends!
The ePaper module is a great way to display the data received from a sensor, such as the CM2302 temperature and humidity Sensor, or the BME680 air quality sensor. The ePaper needs up to 2 seconds to refresh the screen. You can use the ePaper print number block to send a number value to the ePaper. 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.
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.
Your display should update and display the values below which shows the first few iterations of the repeat item loop.
After initializing the display, set the ePaper font color block to black, and the font background to white. 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 ePaper 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 every second and we are able to see the value before the screen is cleared to allow for the next value.
Numbers are text too - From the program above, you can see that the ePaper font color block works with the ePaper print number block, just the same way it does with the ePaper print text block. Likewise, the ePaper text size block works with the ePaper print number block.
So, as long as the extra fonts are installed in upper EEPROM, you can display your project's sensor values in large bubble numbers if that's what you want!
What if you took out the clear screen command in the countdown program above and ran the program again? The program will display a countdown, and it will display 100 the first time around the loop. The second time around the loop it will display 990 and the third time around it will display 980 and so on. The reason for this is because the last value left behind when displaying 100, did not clear. This was not an issue when the screen was being cleared however you may find yourself in situations where you may not want to use the clear screen command.
Thankfully there’s a technique to mitigate this issue.
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.
Here is a challenge that combines what you have learned so far.
The ePaper module displays shapes as well as text and numbers. This means that you can create images on the ePaper 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!
The easiest thing to draw is a single pixel. The following program will draw 100 random pixels.
The random number blocks provide a random value between 0 and the maximum screen dimension, given by the ePaper max height and ePaper max width blocks. These numbers are then used to set the position of the pixel drawn by the ePaper draw pixel block. This then repeats and updates the screen 100 times, drawing 100 different pixels on the ePaper screen. The updating of the screen slows down the process just enough so that you can see the pixels appear.
To draw a line, you need to define a start and an end point - the ePaper draw line block takes two x/y coordinates:
The following program will draw 10 different lines.
Taking Shape — In addition to pixels and lines, there are blocks that draw circles and triangles. Each shape has a fill setting that can be changed, but the shapes themselves are defined differently:
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,300) - both points are off-screen.
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.
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.
The ePaper module is able to display bitmap images as well as text that’s formatted to a .bmp file. The first thing you want to have is a BMP file ready to load onto a micro SD card.
If you don’t have one you can convert a file to BMP format using MSPaint, or any online file converter (such as this one [11]). Be sure to select the monochrome setting within the file converter and size your bitmap image dimensions a bit smaller than the display dimensions in units of pixels.
If you want to include text in you bitmap image try using something with the word “console” in the font title, as they were designed for displays. For example, Lucida Console was used for the hashtag below the logo, overlaid on a screencapture using the Snagit editor:
Keep in mind that the ePaper is slow to update and will take approximately 45 seconds to display an image.
What is the outcome on the screen?
What is the outcome on the screen?
If you want to enhance your ePaper projects with audio, there are a few things to take into account.
Both the ePaper draw image block and the WAV play block both access files stored on your Activity Board’s SD card. However, the ePaper draw image block lets go of the SD card after fetching the .bmp file, while the WAV play block keeps ahold of the SD card for itself until you release it with a WAV stop block.
So, it is recommended that you draw your bitmap image onto the ePaper first before playing your WAV file. By arranging your blocks to draw the image first, the ePaper will begin the process of drawing your image while the Wave file block plays sound right after.
To hear the sound coming from your board when it plays the WAV file we recommend you use this “Hamburger Style” speaker (#900-00018) [3] that easily connects to the Activity Board’s audio jack.
What is the result?
Links
[1] https://www.parallax.com/product/28084
[2] https://www.parallax.com/product/32912
[3] https://www.parallax.com/product/900-00018
[4] https://learn.parallax.com/tutorials/language/blocklyprop/getting-started-blocklyprop-solo
[5] https://learn.parallax.com/tutorials/language/blocklyprop/simple-blocklyprop-programs-propeller-boards
[6] https://solo.parallax.com/
[7] https://learn.parallax.com/sites/default/files/content/AB-Blockly/Projects/ePaper/Project106697-ePaper-Font-Display-Sans.svg
[8] https://learn.parallax.com/sites/default/files/content/AB-Blockly/Projects/ePaper/Project106698-ePaper-Font-Display-Serif.svg
[9] https://learn.parallax.com/sites/default/files/content/AB-Blockly/Projects/ePaper/Project106700-ePaper-Font-Display-Script.svg
[10] https://learn.parallax.com/sites/default/files/content/AB-Blockly/Projects/ePaper/Project106701-ePaper-Font-Display-Bubble.svg
[11] https://image.online-convert.com/convert-to-bmp