Ceci est une ancienne révision du document !
First, I want to wish all our readers a very happy holiday season. No matter what you wish to celebrate, please do so safely! Yes, we are going to talk about more graphics for our MicroController projects. Yet again, we will be using the SSD-1306 for the display, and, for the microcontroller this time, we’ll go back to our ESP-32 generic. Now, the reason for this article is to take “standard” graphics and convert them into something that can be displayed on a 2-color (black and white) SSD-1306 OLED display. It is not as straightforward as one would expect. We’ll need to use GIMP or PhotoShop to do the conversion which is not terribly difficult, but there are some steps involved that you will need to pretty much follow in the order as presented to accomplish this very important step. We’ll also need to use the mpfshell utility we discussed back in FCM#174 (part 8 of the Micro This Micro That series) to transfer the image files to the microcontroller. The version we used then was 0.9.2.
Before we actually get started, I need to thank Martin Fitzpatrick for the wonderful writeup on using PBM files and the micropython code to support it. His website is https://www.mfitzp.com/tutorials/displaying-images-oled-displays/ . The first thing that we need to have is some image files. I’m going to use weather icons that I found at https://iconstore.co/icons/rns-weather-icons/. The download file contains monochrome images in many formats. For ease of use, I decided to use the images in the PNG folder. The 70 images are monochrome PNG files that are sized 96×96 pixels. The next step is to convert the images we wish into PBM format. We’ll use GIMP to accomplish that. Open GIMP and load the image you want. We’ll use the weather_icon-47.png file for this tutorial. Since the image is 96×96 pixels, and our display is at best 128×64, we’ll want to pick something slightly smaller. Let’s pick 50×50. Select Image | Scale Image from the menu bar.
Highlight the Width value and change it to 50. Then simply press the {Tab} key to automatically set the Height value. Click on the Scale button to make the change. Now we want to invert the image so the black pixels become white. Select Colors | Invert from the menu bar. Now we need to convert the image to a 1-bit-per-pixel image. To do this, select Image | Mode | Indexed from the menu bar. You’ll see a dialog pop up that looks something like this. Make sure you have Use black and white (1-bit) palette selected and Remove unused and duplicate colors from colormap selected as well. Select Floyd-Steinberg (Reduced color bleeding) in the Color dithering dropdown, then click on the Convert button. Finally, we need to export it to our .pbm file format. Select File | Export As… from the menu bar, then, in the dialog, change the extension from .png to .pbm and then click the Export button. Another dialog pops up asking the Data formatting type. You want to make sure that Raw is selected then click the Export button.
Your image should now look like this. That’s it for that part. It wasn’t too very painful – detailed, but not painful. Now we want to upload this image to our microcontroller. Again, I use mpfshell to do this (please see my note near the bottom of the article on using mpfshell). Next, we’ll look at our code to display it on the OLED display. We’ll name our file graphx32.py since we are using it on an ESP-32 generic microcontroller. As always, we need to import some libraries. We need the ssd1306 and framebuf libraries, as well as the SoftI2C and Pin libraries from the machine library. Next we need to define the display object for the display (top right). Now we will open the icon image file and do three readline calls. This gets the Magic Number, the Creator comment, and the dimension of the image from the image file header (we’ll talk about these in a moment), and finally the data of the image itself (middle right).
The last things we need to do are load the image data (without the header information) into the framebuffer, fill the display with black, blit the data to our desired position, and call the display show method. The 50,50 in the first line of the next section refers to the size of the image. If it is not 50×50, set it to the correct size (bottom right). The P4 is the identifier that the file is actually a PBM file. (There is another PBM format that uses a P1, which denotes a “Plain PBM” file). The second line as you can see is a comment that states that the file was created by GIMP. Finally you can see that the image dimensions are, as we expected, 50 x 50 pixels. This information will be important if you don’t remember what the size of the image file will be. When you run the program, your display should look like this. Using this method is (in my mind) much better than converting images to a bytearray. It takes a few more lines of code to use the PBM file method, but I find it much easier to work with.
You might not want to have to deal with GIMP everytime you want to convert a PNG file to PBM. Based on the steps we followed using GIMP to convert the file, I threw together a quick and VERY dirty Python program to do the conversion. We’ll use weather_icon-49.png for this part of the project. Name your file ConvertSingle.py . When you run the program, it should just take a moment to finish and you’ll have a nice 32 x 32 PBM format image. There is a small problem with the file we created using the PIL library. There doesn’t seem to be a way to set the Creator Comment in the header of the image file. Therefore, we need to make a small change to our micropython file to handle the lack of the comment. We need to change the with open code to the following (bottom left)…
Since the header comment (according to the specs that I can find) always starts with a #, we can simply check the value of the second line read to see if it starts with the pound symbol (or hash sign for all you social media users). If so, then we simply read the next line. If it doesn’t, we don’t want to try to read another line. There will only be two lines in the header, not three. If we try to read three and the comment doesn’t exist, the data portion of the file will be short and thereby corrupt. By using the scheme above, it will handle both cases properly. Since the new image is only 32×32, be sure to change the line that loads the data into the frame buffer to… fbuf = framebuf.FrameBuffer(data, 32, 32, framebuf.MONO_HLSB) You can see from the image below, that the image created by our Python program works just fine. I’ve placed all the code for this month’s article, along with a couple of sample images, on my github repository at https://github.com/gregwa1953/FCM176_MicroThisMicroThat. To run the above code on the RPi Pico, I had to make a very few changes – you can find the code file in the zipped repository as graphxPico.py. I hope that you and your family and friends have a happy and safe holiday season.