Skip to content

9. Programming & Upgrading the Firmware (ESP32)

Jump to bottom
John edited this page Jan 5, 2023 · 9 revisions

As of 10/1/21, the ESP32 comes programmed with the control board

For the TCD to operate, you must compile the software, and program the ESP32 dev module. You can use you own or the one that comes in the kit. If you're familiar with the Arduino IDE or PlatformIO, this process is fairly simple.

First, download the repository. This can be done by downloading the Zip file, and extracting or opening in Github Desktop

If using the Arduino IDE:

  1. Navigate to the /Software/src folder
  2. Open timecircuits.ino
  3. You will be asked to create a folder - click yes, then Sketch > Show Sketch Folder, and copy the other files from Software/src into Software/src/timecircuits/
  4. If you don't already have the ESP32 Arduino framework installed:
    1. Go to File > Preferences
    2. Add the URL https://dl.espressif.com/dl/package_esp32_dev_index.json to Additional Boards Manager URLs
    3. Go to Tools > Board > Boards Manager, then search for ESP32, and install the latest version by Espressif Systems
  5. Go to Tools > Manage Libraries
  6. Search and install the following libraries:
    1. OneButton
    2. ESP8266Audio
    3. RTClib (Adafruit)
    4. WifiManager (tzapu, tablatronix - not the alpha version, at least v0.16)
    5. Keypad (Mark Stanley, Alexander Brevig)
    6. Keypad_I2C from this repository - you will need to download Keypad_I2C.cpp & .h and put them in a folder under _C:\Users-user-\Documents\Arduino\libraries\Keypad_I2C_

Compiling and uploading

  1. Make sure ESP32 Dev Module is selected under Tools > Board
  2. Connect the ESP32 to your computer via USB cable, and make sure the correct COM port is selected under Tools > Port
  3. Click the upload arrow in the upper left to compile and upload the software

To program the ESP32 that comes with the kit, you must hold down the IO0 (right button) on the module while "...." is displayed in the upload window.

Uploading the sounds

For this you will need the ESP32 Sketch Data upload tool. There is a great tutorial on how to install this here.

Once you have it installed, go to Tools > ESP32 Sketch Data Upload, and the sounds in the Data folder of the repository will be uploaded to the ESP32

If using PlatformIO/Visual Studio:

  1. Install Visual Studio Code if you haven't already.
  2. Install the PlatformIO IDE extension
  3. Make sure you have the Espressif 32 platform installed - Go to PIO Home (House icon in the lower left blue toolbar) > Platforms, and search for Espressif 32 - install it if necessary
  4. Open platformio.ini under /Software/src - this should open the project in PlatformIO
  5. Make sure your ESP32 Dev Module is connected to your computer via USB
  6. Change upload_port = to the COM port of the ESP32, if needed
  7. Compile and upload the software by clicking the right arrow in the bottom PlatformIO menu, or General > Upload from the left PlatformIO menu

To program the ESP32 that comes with the kit, you must hold down the IO0 (right button) on the module while "...." is displayed in the upload window.

If you get any compile errors, make sure that the proper library dependencies are loaded by referencing what is listed in the platformio.ini and going to PIO Home > Libraries

Uploading the sounds

  1. Click on the PlatformIO icon in the left menu
  2. Under Platform, click on Upload Filesystem Image
  3. The sound files will upload to the ESP32

Upgrading from v1.0

  1. Download the latest .bin file available in the repository
  2. Open the web config portal by entering the IP address of the TCD in a web browser. If the TCD is not connected to WiFi, see the instructions here to connect it to your network
  3. Once the web config portal is loaded, Go to "Update"
  4. Select the .bin file downloaded in the first step
  5. Click "Update" to load the new firmware

Important: After a firmware update, the displays might stay dark or display "WAIT" for up to a minute after reboot. Do NOT unplug the clock during this time.

Loading new sound files

  1. Copy all the files in the "data" folder to the root folder of a fresh FAT32 formatted micro SD card
  2. Turn off the TCD by unplugging it from power
  3. Insert this card into the device
  4. Turn the TCD back on
  5. Install the files through the keypad menu or the web config interface
    1. For the keypad menu - hold down the enter button, then press it until you reach "INSTALL AUDIO FILES". Hold down the enter button for 2 seconds to enter this menu
    2. For the web config portal - it will show an "Audio file installation" option at the bottom of the "Setup" page. Write "COPY" into the empty text field, and click on "Save".
    3. Note that the exact and complete contents of the data folder must be found on the SD card during boot for these menu items to appear
  6. The device will then copy all the default audio files from the SD to its internal flash file system. The SD can (and should) be removed afterwards.

Clone this wiki locally