Ceci est une ancienne révision du document !
CYD (Cheap Yellow Display) ESP-32
Greetings again fellow Sentient Lifeforms. Things here at landing pad 2997 on Terra STILL haven't calmed down at all over the last couple of months, but I’m hoping that as we get through the beginning of Autumn, things will lighten up a bit (before the holiday season hits).
This month, we will dig deeper into the ESP32-2432S028, or the Cheap Yellow Display. Of course, the one I bought is more orange than Yellow to my old eyes, but I won’t call it the COD, since that normally means Collect On Delivery, or to some Cause of Death. So, I’ll pretend that it’s yellow and refer to it as CYD.
This is a really neat little board driven by an ESP32-WROOM with a ILI9341 320 x 240 screen attached. The screen is also a Resistive Touch screen, which makes it rather nice to hold a GUI or to become a Gaming board.
There seem to be many variants of the CYD out there from many different vendors. The one I got (from Amazon) is made by AITRIP. Just make sure that you get a board that is described as ESP32-2432S028R. There seems to be at least three versions of this board (again from various manufacturers). Mine seems to be revision 3, and has not only the USB-C connector but also the old style USB micro. Both work to power and program the board, so if you don’t have a USB-C connector cable yet, you might want to look for the revision 3 board if you can find it.
A quick note here on obtaining the board. There are MANY places that you can get this board from. I used Amazon and got a two-pack of the boards for about $35 USD. There are some places that show getting the board plus a front and back protective plate set for less than $5.00 USD. PLEASE don't fall for that. Even though the entire web page continually says that the board is included, it isn’t. Look for the board to cost somewhere between $12 USD and $20 USD in single quantities. PLEASE remember the old saying “If it seems too good to be true, it probably is”.
As far as I can tell, there are at least four ways to program these boards. The first (and most prevalent on the Internet) is using the Arduino programming language and the Arduino IDE. There are lots of examples of this out there, so I won’t deal with this too much this month. The best place I’ve found is to look at the Random Nerds website (https://randomnerdtutorials.com/cheap-yellow-display-esp32-2432s028r/). This is a really good write up, BUT PLEASE go slowly and carefully. Follow the directions EXACTLY or it won’t work for you.
The second way to program the board is to use MicroPython. There are many (but not as many as for the Arduino code) websites for this. The two very best drivers (currently) are at
https://github.com/jtobinart/MicroPython_CYD_ESP32-2432S028R and https://github.com/rdagger/micropython-ili9341/. The first link also refers to the second. You should download (or clone) both sites and get the libraries from them into a special working folder. More about this in a moment.
The third way to program the board is to use one of the ESPHome. However, I haven’t taken the time yet to investigate this.
Finally, there is a special GUI library called LVGL which works with this (and many other boards) that, for the moment, is best done using Arduino code. You can find a very good tutorial again at the Random Nerds site at https://randomnerdtutorials.com/lvgl-cheap-yellow-display-esp32-2432s028r/. Again, PLEASE go slowly and follow EVERY step.
There is a newish product called platformIO that is a plugin for Visual Studio code, and there are some good tutorials for the LVGL programming using this. I’ll address this in a future article.
To use LVGL on MicroPython, you must create your own MicroPython firmware cut that includes support for LVGL. Believe me when I say, this is not something for everyone. It requires multiple toolkits to be installed and takes a while to do and test. I’ll try to work up a step-by-step instruction set for you in the near future.
Here is what the back of my board looks like. On the left, you can see the USB-C connector in the middle and the old style USB connector towards the bottom.
Connectors
While it looks like there are many available pins for sensors and other connections, there aren’t as many as you might think. Along the bottom of the board, in the middle, is the MicroSD slot, and just to the right of that are two JST connectors that appear to be STEMMA Qwiic compliant, but they are not. They are 1.25mm and the normal Qwiic connectors are just a little bit smaller. The two boards that I purchased each came with one connector for this, and most of the boards that I looked at seem to come with one as well. The CN1 connector (closest to the MicroSD slot) is normally used to connect I2C devices. Unfortunately, the “normal” ESP-32 I2C pin sets can’t be used, since the backlight takes up one of those normal pins. I’ve created a “cheat chart” for you…
Using the (hopefully) included JST cable, the pins (looking from the display side of the board and the connector at the bottom) from left to right, are [in the table below].
As I said, you can’t use the “normal” I2C pin assignment. You have to “roll your own”. Here is the MicroPython code, using an SI7021 Temp/Humidity sensor:
i2c = SoftI2C(scl=Pin(27), sda=Pin(22), freq=100000)
si7021 = SI7021(i2c)
Of course, you have to import the library first. This can be just about any I2C device as long as you get the pins defined correctly.
If you want to use a DHT11 or DHT22, you can use this pinout as well. Here’s (above) a pinout for the DHT22. You only need to use three of the four pins.And the MicroPython code to support it…
#
# initialize si7021 Temp & Humidity sensor
#
import dht
d = dht.DHT22(Pin(27))
d.measure()
Of course, you can’t use the DHT device at the same time for an I2C sensor on CN1.
If you want to use the P3 connector, here (below) is a pinout of it.
There are a couple of things here you need to be aware of. First, the red wire is NOT 3.3v, but a GPIO pin. Don’t try to use this to power your device. In addition, the yellow wire is the same GPIO pin as the blue wire on connector CN1. Why in the world they did this, I can not speculate. Just be aware that your best bet for using I2C devices… use CN1.
One other connector you should be aware of is the P1 connector, which is next to the USB-C Data/power port. This is mostly to be used as a SERIAL port. From top to button the pins are shown above.
You might wonder why GPIO 01 and GPIO 03 are marked with a trailing question mark. That’s the information I have and it’s included that way. I wouldn’t try to use these pins as GPIO pins at this point. More research needs to be done!
Onboard RGB LED
One of the other things I should tell you about is that the screen isn’t your “normal” RGB display. It uses color565. You can find more information, and their justification for creating such a thing, at https://rgbcolorpicker.com/565.
Drivers
The best place that I’ve found to get drivers for MicroPython is https://awesome-micropython.com/.
As I stated earlier, the two very best drivers (currently) can be found at https://github.com/jtobinart/MicroPython_CYD_ESP32-2432S028R and https://github.com/rdagger/micropython-ili9341/.
Make note of the fact that you must have the micropython-ili9341 drivers in order to use the Micropython_CYD driver. More about that in a little bit.
JST Connectors
The speaker connector (P4) requires a 2 pin 1.25mm JST connector which is not usually included.
The IO connectors P1, P3 and CN1 are 4 pin 1.25mm JST connectors. At least one is included with most CYD boards.
Since these JST connectors are NOT the same as “normal” STEMMA QT/Qwiic JST connectors that you can easily find, I dug around on Amazon.com and found a couple of candidates.However, I have NOT verified that these will work.
For the Speaker connector (2 pin), you can try… https://www.amazon.com/Letool%C2%AE30-1-25mm-Female-Connector-Cables/dp/B013JRWCBU
For the IO connectors (4 pin) you can try… https://www.amazon.com/Micro-Connector-Socket-1-25mm-Female/dp/B09DYLY95R/ref=sr_1_3?s=electronics&sr=1-3
In case you want to “roll your own” connectors, there seems to be a DIY kit that contains 2,3,4,5,6,7,8,9 and 10 pin empty connectors with wires ready to insert into the blank connectors. Again, I don’t currently know if this is a good kit. You can check it out at… https://www.amazon.com/1-25mm-Connectors-Pre-Crimped-Pixhawk-Silicone/dp/B07S18D3RN/ref=sr_1_1_sspa?s=electronics&sr=1-1-spons&sp_csd=d2lkZ2V0TmFtZT1zcF9hdGY&psc=1
MicroPython Coding
You need to have cydr.py, ili9341.py, xpt2046.py, and the xglcd_font.py on the CYD device, and NORMALLY they are put into a folder named lib. You CAN have them in the root of the device, but it’s standard practice to have them in the lib folder.
Now I’m going to tell you why you need both the CYD and the ili9341 driver sets.
While you can use just the ili9341 drivers, there is a bit of a problem. This was designed to be a very generic low-level driver set, and can be used with any ili9341 display board, not just the one on the CYD board. The CYD driver set uses the ili9341 drivers and wraps all of the functions of the display driver, the touchscreen, and the RGB LEDs, into a higher level library that is MUCH easier to use and focuses on just the CYD board.
The ili9341.py driver concentrates on the Display board and some generic RGB LED functions. There are two other drivers included, which are xpt2046.py which deals with the touchscreen functions and the xglcd_font.py which allows you to use some different fonts instead of a very simple 8×8 font. The ili9341.py driver includes things like drawing lines, rectangles, circles and drawing text.
The CYD driver imports the display driver and touchscreen libraries for you, and provides a single interface to all of them that is (as I said above) MUCH easier to use. If you want to use the special fonts, you will have to import that yourself into your program.
Another reason to use the CYD driver is that the ili9341 driver is so generic that the demo programs won’t run on the CYD because the SPI interface uses different pins that the generic interface provides by default. For example, the demos initialize the SPI interface like this (shown above).
You can see that, while the sck and mosi pins are the same between both drivers, the dc, cs and rst pins are all different. The CYD driver is already set up for this.
Using the CYD driver is really easy. First, you have to import the library, then initialize an object of the CDY master object.
from cydr import CYD
cyd = CYD(rgb_pwm=False, speaker_gain=512, displaywidth=320, display_height = 240, wifi_ssid=None, wif_password=None)
Most of the parameters to the CYD object are optional. Notice that there is wifi support built into the CYD driver as well, making it very flexible.
So, now that we have instantiated the CYD object and named it cyd, you can clear the display with a simple call like this…
cyd.display.clear()
To print text on the display is just as easy.
text = “This is a test!”
cyd.display.draw_text8x8(xposition, yposition, text, colour)
In the initialization line, notice I placed the device in “landscape” mode with the long side (320) of the display along the top and bottom and the short sides (240) on the right and left sides.
In this mode, position (0,0) is at the top-left corner of the display (when it is oriented with the USB plug on the right side of the device).
I’ve created a github repository at https://github.com/gregwa1953/MTMT-209 that will hold a few of the demo programs that I wrote for my CYD.
One of the demos that I’ve included is an app that uses the OpenWeatherMap API over a WIFI connection to get the current outside conditions of my location and a DHT22 Temp/Humidity sensor to show the inside temperature and humidity. Of course, they both use a different polling time. Here is a very poor image taken with my cell phone camera of the CYD screen.
That’s it for this month. I’m certain that we will readdress the CYD in more than one future article.
Until next time, as always; stay safe, healthy, positive and creative!