Programming the T-WATCH-2020 — Part 1

Using the Arduino IDE to program the LILYGO T-WATCH-2020 v1 — why is this so hard? LILYGO are a chinese company who sell products based on open-source hardware and software. The T-WATCH-2020 (Figure 1) is an ESP32 based 1.54" touch display “smart” watch. Make sure that you read the entire article before starting or you may “brick” your new programmable watch! Part 1 of this series will describe setting up the Arduino Development Environment, and Part 2 will provide details of the TTGO T-Watch Library (which is great but has a poorly documented API).

Figure 1. T-WATCH-2020 v1 with Default Firmware

The T-WATCH is clocked at 40 MHz, it has 16 MB of QSPI FLASH memory, 520 KB of SRAM and 8 MB of PSRAM (Pseudo-Static RAM — note that only the lower 4 MB of this may be usable). The pin-map for the ESP-32 can be found on the TTGO GitHub repository. The T-WATCH-2020 peripherals include:

• A BMA423 three-axis accelerometer, with built-in step counting algorithm, activity recognition / tracking, and advanced gesture recognition. The BMA423 can communicate via SPI or I²C but the T-WATCH uses I²C (default address 0x19).
• The PCF8563, a CMOS Real-Time Clock (RTC) and calendar optimized for low power consumption. Features include a programmable clock output, an interrupt output, and voltage-low detector. It communicates via the two-line bidirectional I²C-bus (read address 0xA3 and write address 0xA2). Maximum bus speed is 400 kbit/s.
• An AXP202 Power Management Unit (PMU). The AXP202 is a single cell Li-Battery PWM Charger and Power System Management IC. It is used for obtaining power from three different power sources, single-cell Li-Ion battery, USB port, and an AC-adapter. It communicates with the ESP-32 using I²C (read address 0x69 and write address 0x68).
• A MAX98357A I²S PCM input Class D audio amplifier which provides Class AB audio performance with Class D efficiency.
• A LQ-S1 3.7 V, 380 mAh, 1.4 Wh, LiPo Battery (Figure 2).
• A 1.54 inch, 240 x 240 pixel, Sitronix ST7789V LCD Display with capacitive touch screen. The ST7789V is a single-chip controller/driver for 262K-colour, graphic type TFT-LCD’s. The display is controlled using SPI and the touch screen by I²C.

Figure 2. LQ-S1 LiPo Battery

Available T-WATCH Models

There are a number of different T-WATCH versions available from LILYGO. The features of these different models are summarised in Figure 3. We have the T-WATCH-2020 v1.

Figure 3. T-WATCH Feature Comparison.

• [1]: Need expansion board to support
• [2]: The buttons are AXP202 PEK programmable buttons

Development Environment

The most common ways to program the T-WATCH-2020 in C/C++ are using the Arduino IDE, ESP-IDF (Espressif IoT Development Framework) or in MicroPython using PyCharm or VSCode plus Pymakr extension. There are obviously other options as well.

Figure 4. T-WATCH-2020 GPIO Definitions (source)

We will use the Arduino IDE because that is what we are most familiar with and frankly it is the easiest to get up and going. In particular, we are using the new fancy version 2.0.2.

[embed]Espressif ESP32 Tutorial — Part 2 Programming with the Arduino IDEmedium.com

The first thing that we need to do is add the TTGO_TWatch_Library to our Arduino Environment.

Figure 5. TTGO_TWatch_Library GitHub Repository

Go to the Library, click on the green button called <> Code and then click on Download ZIP(Figure 5). This will download the library as a zip file to your usual browser download location. Open up the Arduino IDE, select Sketch in the tool bar (Figure 6), then Include Library >, then Add .ZIP Library…

Figure 6. Adding an Arduino Library

This will open up a file dialogue which will allow you to select the zipped library file that you downloaded earlier. Select this and the library will be installed.

Figure 7. TTGO TWatch Library Examples

You can test whether the library has been installed by opening File > Examples > TTGO TWatch Library (Figure 7).

Figure 8. Adding ESP32 Options to the Board Manager

Next up we need to add the ESP32 TTGO T-Watch files to the board manager. To do this:

• open the Preferences window in the Arduino IDE.
• Enter https://dl.espressif.com/dl/package_esp32_index.json into Additional Board Manager URLs field. You can add multiple URLs, separating them with commas.
• Lastly, open Boards Manager from the Tools > Board menu and install the *esp32* platform — see Figure 8.

After this you will be able to select your ESP32 board from the Tools > Board > esp32 > TTGO T-Watch menu (Figure 9). In a perfect world you would now be able to compile and upload sketches to your T-Watch, if you are using a Mac then you may have some extra hoops to jump through.

Figure 9. TTGO T-Watch Board Selected

WARNING!!! Changing your watch firmware could "brick" your TTGO T-Watch.

“python”: executable file not found in $PATH

If you get this error when you first try to compile and upload one of the example files to your T-WATCH, it may be because you are using a Mac. Apple hasn’t bundled Python 2.7 since macOS 12.3 (as Python 2 has not been supported since January 1, 2020 and no longer receives any bug fixes, security patches, or other changes). Python 3 also does not come preinstalled on macOS. In order to install Python 3 you will need to first install the Apple Command Line Tools. To do this, open up your favourite Terminal program and type:

xcode-select — install

Then go and make a cup of tea — download and install will take a while! The first thing you will want to know is what version of Python 3 do you have installed (if any) — in Terminal type python3 --version. My machine initially had:

Python 3.8.9 (default, May 17 2022, 12:55:41)
[Clang 13.1.6 (clang-1316.0.21.2.5)] on darwin

This is not the latest version and we will upgrade it. To determine the version of Python 2 installed, in Terminal type python --version:

dsuch@DS-M1-MacBook-Pro-9 ~ % python --version
zsh: command not found: python

So Python 2 is not installed, which is fine, we don’t need it. To install the latest version of Python 3, type:

brew install python

Towards the end of the install, you may get a couple of errors (Figure 10).

Figure 10. Brew install Python Errors

To fix these, create the required directory and give it appropriate permissions (enter your password when requested):

dsuch@DS-M1-MacBook-Pro-9 ~ % sudo mkdir /usr/local/Frameworks
dsuch@DS-M1-MacBook-Pro-9 ~ % sudo chown $USER /usr/local/Frameworks

Then try to reinstall python with brew install python. If you get the following warning:

Warning: python@3.10 3.10.8 is already installed, it’s just not linked.
To link this version, run:
 brew link python@3.10

Run the suggested command (brew link python@3.10) in the Terminal. Finally, we need to link the python command to python3. To find out where your Python 3 executable is located, type which python3:

dsuch@DS-M1-MacBook-Pro-9 ~ % which python3
/usr/local/bin/python3

Use this path to link python to python3 with the ln command:

sudo ln -s /usr/local/bin/python3 /usr/local/bin/python

You can check that this has worked by comparing the version returned for the two commands (Figure 11) — they should now be the same.

Figure 11. Checking that the link command worked

FINAL WARNING!!! Changing your watch firmware could "brick" your TTGO T-Watch.

Failed to write to target RAM (result was 01070000)

After installing python we could now upload to the watch but doing so killed it and returned the error shown in Figure 12. This may be just another macOS issue. I’m running a MacBook Pro (M1 Pro, 14-inch, 2021) and the problem is not having a driver for the USB to serial chip used in the T-Watch.

Figure 12. Progress?

Installing the Correct USB Driver

ESP32 development boards typically use either the CP2104 or the CH340 USB to UART bridge. The schematic diagram for the T-Watch 2020 is hard to find which suggests the “Open Hardware” description is a bit misleading. Nevertheless, a French chap managed to get a copy from TTGO and published it on his website. The relevant part of the circuit is shown in Figure 13.

Figure 13. T-WATCH-2020 UART Schematic v1.4 (source)

The schematic states that chip U6 is a CP2104, however we have no idea if this is the latest schematic and we had read that CP2104 drivers didn’t work with the T-Watch. We installed the CH340 drivers and this did work. After you have the driver installed you can confirm the USB Product ID and Vendor ID (Figure 14), which are consistent with the chip being from the CH340 family. We realise that this is a bit of a chicken/egg situation.

Figure 14. Confirming PID & VID — About This Mac > System Report > USB

Once you have the Product ID (PID) and Vendor ID (VID) for a USB device, there are websites that you can use to lookup the relevant chip (Figure 15).

Figure 15. Web Lookup of PID and VID (source)

How to Install the CH340 Driver (macOS)

The CH340 is made by WCH. There are a few variants of the CH340, the CH340G requires an external crystal oscillator while the CH340C includes a built-in crystal oscillator. They all convert USB data to serial UART and vice versa! The macOS driver for the CH340 (and variants) can be downloaded from the WCH Drivers & Tools web page. Installation instructions for this driver are available in the WCHSoftGroup GitHub repository. We will include a quick install summary here but check the original source just in case something changes.

1. Download the driver from the website and unzip the file to a local installation directory.
2. Assuming you are using macOS 11.0 or above, double click the dmg file in the unzipped directory to mount it. Drag the CH34xVCPDriver.app file into applications (Figure 16).
3. Open the Applications and double click on the app you just transferred. then click Install (Figure 17). MacOS High Sierra 10.13 introduced a new feature that requires user approval before loading third-party kernel extensions. Go to System Preferences — Security & Privacy and click Allow (Figure 18).

Figure 16. Installing the CH340 Driver

Figure 17. The CH340 Driver App

Figure 18. Security & Privacy — Allow Driver Install

After this the driver should be successfully installed (Figure 19). You can confirm this by looking at About This Mac > System Report > USB and checking the PID and VID (Figure 14). More importantly, the Arduino IDE should now be able to see the watch attached to the USB port.

Figure 19. Driver Installed

Coming Soon — Part 2 (Using the TTGO T-Watch Library)

Part 2 will provide details of the TTGO T-Watch Library (which is great but has a poorly documented API). We will develop a custom watch face and in the process expose some of the useful API commands available.

[embed]Programming the T-WATCH-2020 — Part 2 Using the TTGO T-Watch Libraryreefwing.medium.com

If you enjoyed this article and would like to help support my writing, then please subscribe to become a Medium Member. I will get a portion of your subscription fee and you get access to every story on Medium. Alternatively, you can buy me a coffee!

[embed]Join Medium with my referral link - David Such Read every story from David Such (and thousands of other writers on Medium). Your membership fee directly supports…reefwing.medium.com