Getting started with Wireless Tag's WT32-SC01 Plus using SquareLine Studio, LVGL, and OTA updates.
I recently bought a WT32-SC01 Plus but quickly grew frustrated when it came time to use it. I found plenty of YouTube videos demonstrating it's amazing screen and performance, all in an under-$30 device, but somehow the "how did you compile then upload that application to the board?" question was never answered. After plenty of digging and experiments and frustrating hours, here's a detailed description of what I learned. Factual corrections and further contributions welcomed.
- What you need to know right now
- Programming
- OTA updates
- Squareline Studio
- Building This Example
- Screenshots
- GPIOs
- Partitions
- 3D-printed cases
- A WT32-SC01 Plus board with programmer
- 8-pin MX1.25 PicoBlade dongles if you plan on using GPIOs
or
- A WT32-SC01 Plus board without programmer
- 7-pin MX1.25 PicoBlade dongles (get some 8-pin ones too if you plan on using GPIOs)
- A normally-open momentary push button
or
- A WT32-SC01 Plus board without programmer
- 7-pin MX1.25 PicoBlade dongles (get some 8-pin ones too if you plan on using GPIOs)
- A 3.3V USB-to-Serial communication board
- 2.54mm/0.1" pin header with suitable female connector housings
and:
- ESP-IDF v5.0
- SquareLine Studio
- USB-C 2A power supply
Unlike other ESP32 development boards, you can't simply connect the WT32-SC01 Plus via its USB-C port and let the Arduino IDE do its magic. You have to either use the custom programmer provided by WirelessTag, or use the USB-C port and (sometimes) explicitly put it in flashing mode. As the programmer wasn't included with the board I purchased and the explicitly-put-the-board-in-flashing-mode wasn't documented anywhere, it was a particularly frustrating step to figure out.
If you bought the version that includes the programmer, see the "Using the WT programmer" section.
If you have a momentary-closed button, see the "Using the USB-C port" section.
If you are particular masochistic (or ignorant of the above-two options like I was), see the "Using your own USB-to-serial board section
Pin | ESP32 Pin | Voltage Range | Remark | Boot Button | Serial |
---|---|---|---|---|---|
1 | +5V | 5V | USB-to-serial not sufficient as power source | open | open/5V |
2 | +3.3V | 3.3V | For reference, not for power input | open | open |
3 | TXD0 | 3.3V TTL | open | Rx | |
4 | RXD0 | 3.3V TTL | open | Tx | |
5 | EN | 0-3.3V | Resets the ESP32 when pulled to GND | open | open |
6 | GPIO 0 | 0-3.3V | Enters flashing mode when pulled to GND during reset | button | GND/open |
7 | GND | 0V | button | GND |
If you ordered a WT32-SC01 Plus that came with its own custom programmer, you can connect it directly to the DEBUG port on the back of the WT32-SC01 Plus. It exposes the familiar EN and BOOT buttons.
If not, you can order a programmer here.
Unfortunately, the 6" white USB-C cable that came with it was either bad or it is a power-only cable. When using it, the programmer and WT32-SC01 Plus powered up nicely, but my Mac never created the serial device and I was unable to program anything. Once I switched to a known-good data cable, everything worked smoothly.
-
If you are using a Windows or MacOS machine, make sure you have the necessary driver installed for your USB-to-serial board. It is probably going to be a CP210x or CH34X driver.
-
Flash your application using the command
idf.py flash
. The device gets put automatically into flashing mode, and it will automatically reset upon completion and start running your program. -
Should the flashing application cannot find your device, force it into flashing mode by pressing your EN and BOOT buttons on the programmer, Release the EN button first, then the BOOT Button.
-
Flash your application using the command
idf.py flash
. Wait until the flashing process completes with aHard resetting via RTS pin...
message. -
To run your application, reset the WT32-SC01 Plus again by pressing on the EN button.
IMPORTANT Make sure you are using a USB data cable, not a power cable. The latter will power the unit but will not be able to program it. I suspect the short white USB-C cables supplied with the units are power cable and why I originally assumed you could not program via the USB-C port.
You can program via the USB-C port if the device is put into flashing mode.
If the device is running normally, the idf.py flash
command will automatically reset it and put it into flashing mode.
But if it is hung or crashed, it will have to be put into flashing mode manually.
However, since there is no BOOT button, you have to manually short the GPIO0 and GND pins on the Debug Interface.
Using a 7-pin MX1.25 PicoBlade dongle and a momentary-closed push-button, create a cable to connect the GPIO0 and GND pins to the normally-open terminals of the button.
Here's my DIY programming cable Boot Button.
I was told of this option after hours of scouring the web
and finally using a USB-to-serial programmer using the same approach as all other ESP32 MCUs.
That this Boot Button doubles as a release for all my pent-up frustration is no accident.
The following steps assume you have an application succesfully compiled using idf.py build
(see Build This Example section).
To program, then run your application with the serial monitor, connect the WT32-SC01 Plus via its own
USB-C port directly to your computer.
-
If you are using a Windows or MacOS machine, make sure you have the necessary driver installed for your USB-to-serial board. It is probably going to be a CP210x or CH34X driver.
-
Flash your application using the command
idf.py flash
. If the device gets put automatically into flashing mode, it will automatically reset upon completion and start running your program. -
If the flashing application cannot find your device, force it into flashing mode by pressing your Boot Button, then pressing the
RST
button on the back of the WT32-SC01 Plus. Release the RST button first, then the Boot Button. -
Flash your application using the command
idf.py flash
. Wait until the flashing process completes with aHard resetting via RTS pin...
message. -
To run your application, reset the WT32-SC01 Plus again. The serial monitor will be automatically connected.
Using a 7-pin MX1.25 PicoBlade dongle and a 2.54mm/0.1" pin header connector housing that matches your board, create a cable to connect the TX, RX, and GND pins on the Debug Interface to the RX, TX, and GND pins respectively on your USB-to-serial communication board, and using a separate 1-pin connector housing, connect the GPIO0 pin on the Debug Interface to a second exposed GND pin on your USB-to-serial communication board. It is important that it be possible to disconnect the GPIO0 wire from the USB-to-serial board without disconnecting the other wires.
Here's my DIY programming cable. I did connect the 5V line so I could easily identify which side of the connector was "up": the red wire goes with the VCC pin. Notice how the white "GPIO0" wire is connected to a separate exposed GND pin on the programmer.
The following steps assume you have an application succesfully compiled using idf.py build
(see Build This Example section).
To program, then run your application optionally with the serial monitor, power the WT32-SC01 Plus via its own
USB-C port as well as connecting your serial board to a USB port on your computer.
-
If you are using a Windows or MacOS machine, make sure you have the necessary driver installed for your USB-to-serial board. Refer to the documentation provided by your board vendor for details. It is probably going to be a CP210x or CH34X driver.
-
To enter flashing mode, connect the GPIO0 wire to the GND pin, then press the
RST
button on the back of the WT32-SC01 Plus. -
Flash your application using the command
idf.py flash
. Wait until the flashing process completes with aHard resetting via RTS pin...
message. Skip to step 6 if you are not using the serial monitor to debug your application. -
Leave the GPIO0 wire connected to the GND pin and reset the WT32-SC01 Plus again.
-
Start the serial monitor using the command
idf.py monitor
. Wait until the monitor is running indicated by the following message:
--- idf_monitor on /dev/cu.wchusbserial54340143141 115200 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
- To run your application, disconnect the GPIO0 wire, then reset the WT32-SC01 Plus again.
This trivial example application includes over-the-air (OTA) update cability. Once the example application is flashed using the serial communication board, you can use OTA updates instead for subsequent updates but takes longer to flash (approx 2mins). As long as you do not modify the code up to the point where the spash screen is replaced with the main screen, OTA should remain functional.
-
Build the latest version of the application using the command
idf.py build
-
Start the OTA server using the command
python webserver.py
-
Reset your WT32-SC01 Plus
-
While the splash screen is displayed, tap the project name 5 times to trigger an OTA upgrade.
For the upgrade to complete succesfully, you must have correctly specified your WiFi credentials and OTA server certificate when building.
To add support for the WT32-SC01 Plus, copy the content of the SquareLine/boards
directory into your Squareline Studio installation using the command
$ cp -r SquareLine/boards/* <Path to Squareline Studio installation>/boards
e.g. on my Mac:
$ cp -r SquareLine/boards/* /Applications/Squareline_Studio.app/Contents/boards
Restart Squareline Studio if it is was already running.
You'll find the Squareline Studio project for this example in SquareLine/SquareLine_Project.spj
.
When exporting your UI files, export them in the main/ui
directory
After cloning this respository:
-
Update the component submodules using the commands
git submodule init
andgit submodule update --progress
. Be patient. This can take a while. -
Generate a self-signed certificate for the OTA https server using the command
openssl req -x509 -newkey rsa:2048 -keyout server_certs/ca_key.pem -out server_certs/ca_cert.pem -days 365 -nodes
. When prompted for theCommon Name (CN)
, enter the IP address of the server that the WT32-SC01 Plus will connect to. -
Set your target device using the command
idf.py set-target esp32s3
-
Copy the file
secrets.h
into the 'main' directory, and edit it to specify your WiFi credentials and OTA server certificate. The certificate can be found in the fileserver_certs/ca_cert.pem
. ToDo: replace with menuconfig and get the certificate compiled into the binary directly. -
Build the demo application using the command
idf.py build
Only 6 GPIOs are exposed via the 8-pin MX1.25 PicoBlade Extended I/O interface.
Pin | ESP32 Pin | Voltage Range | Remark |
---|---|---|---|
1 | +5V | 5V+/-5% | Input or output |
2 | GND | 0V | Ground |
3 | GPIO 10 | 0-3.3V | |
4 | GPIO 11 | 0-3.3V | |
5 | GPIO 12 | 0-3.3V | |
6 | GPIO 13 | 0-3.3V | |
7 | GPIO 14 | 0-3.3V | |
8 | GPIO 21 | 0-3.3V |
This example uses a custom partition for maximum application size. Even though the example application is only 1.4MB, the ESP32-S3 is configured with two 4032KB partitions, the largest OTA partitions you can have.
# ESP-IDF Partition Table
# Name, Type, SubType, Offset, Size, Flags
nvs,data,nvs,0x9000,16K,
otadata,data,ota,0xd000,8K,
phy_init,data,phy,0xf000,4K,
ota_0,app,ota_0,0x10000,4032K,
ota_1,app,ota_1,0x400000,4032K,
Refer to Partition Tables for more details about trade-offs. Note that you cannot modify partitions via OTA. A change in partitions requires serial flashing.
If you want to design a UI in landscape orientation, simply:
- In SquareLine Studio's Project Settings, set the orientation to 90 degrees
- In the file 'main/devices/conf_WT32SCO1-Plus.h', swap the values for TFT_WIDTH and TFT_HEIGHT then set the 'cfg.offset_rotation' in the panel instance configuration to '1'.
- Get my code configurable using menuconfig
Here is a set of resources for 3D printed cases