WT32-SqLn

Getting started with Wireless Tag's WT32-SC01 Plus using SquareLine Studio, LVGL, and OTA updates.

Overview

I recently bought a WT32-SC01 Plus but quickly grew frustrated when it came time to use it. I tried programming it with a simple Arduino example using the 6" white USB-C cable that came with it. The WT32-SC01 Plus powered up nicely running the demo, but my Mac never created the serial device and I was unable to program anything. 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, I'm convinced the 6" white USB-C cable that came with my unit was either bad or it is a power-only cable. Once I switched to a known-good cable, things got easier. Here's a detailed description of what I learned in the process. Factual corrections and further contributions welcomed.

Programming
OTA updates
Squareline Studio
Building This Example
Screenshots
GPIOs
Partitions
3D-printed cases

What you'll need

A WT32-SC01 Plus board with programmer
8-pin MX1.25 PicoBlade dongles if you plan on using GPIOs

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

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

Programming

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

Debug Interface on WT32-SC01 Plus

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

Using the WT programmer

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.

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 a Hard resetting via RTS pin... message.
To run your application, reset the WT32-SC01 Plus again by pressing on the EN button.

Using 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 a Hard resetting via RTS pin... message.
To run your application, reset the WT32-SC01 Plus again. The serial monitor will be automatically connected.

Using your own USB-to-serial board

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).

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 a Hard 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.

OTA Updates

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.

Squareline Studio

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

Building This Example

Make sure you are using esp-idf version 5.0.2. It looks like the IDF installer installs the head of the main branch, not a stable release.

% cd <path/to/your/esp-idf>
% git checkout v5.0.2
% git submodule update
% ./install.sh esp32,esp32s3

After cloning this respository:

Update the component submodules using the commands git submodule init and git 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 the Common 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 file server_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

Screenshots

GPIOs

Only 6 GPIOs are exposed via the 8-pin MX1.25 PicoBlade Extended I/O interface.

Extended I/O Interface on WT32-SC01 Plus

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

Partitions

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.

Lanscape Orientation

If you want to design a UI in landscape orientation, simply:

In the file 'main/devices/conf_WT32SCO1-Plus.h', define the 'LANDSCAPE' symbol.
In SquareLine Studio's Project Settings, set the width to 480, height to 320, and orientation to 90 degrees

ToDo

Get my code configurable using menuconfig

3D-Printed Cases

Here is a set of resources for 3D printed cases

PrintMinion

janick / WT32-SqLn