1. Environment Setup
   1. Windows Setup
      1. Install Git
      2. Create GitHub account
      3. Fork RobotathonESP32 Repository
      4. Set Up Git SSH Authentication
         1. Generate SSH key
         2. Add SSH key to SSH-agent
         3. Add SSH key to Github
      5. Clone Forked Repository
      6. Install USB-UART Bridge Driver
      7. Install 7-zip
      8. Install Preconfigured VSCode
      9. Flash your ESP32
   2. macOS Setup
      1. Install VS Code
      2. Install Git
      3. Install SiLabs UART-USB driver
2. Example Program

Environment Setup

The end goal of this article is to flash your ESP32 with an LED blink program. It will take you from having nothing installed to the full coding environment you’ll need for the competition!

Important software to be installed:

1. VS Code with ESP-IDF
2. Git Bash
3. SiLabs USB-UART bridge driver

For explanations on what each of these applications are, take a look at the FAQ! TODO: WRITE THIS LOL

The exact process to arrive at this goal depends on what OS your computer is running (Windows, macOS, etc.), so this article will be split into Windows and MacOS setup. If you happen to use another OS, then talk to a mentor for help.

Windows Setup

It is highly recommended to follow each component installation in order

Install Git

1. Go to the Git website at https://git-scm.com/downloads
2. Download the 64-bit installer
3. Run the newly downloaded installer and follow the defaults in the installer dialogue
4. Open Git Bash and familiarize yourself with how to navigate the bash terminal (How do I do that?)

Create GitHub account

Go to GitHub and create an account if you do not have one already https://github.com/

Fork RobotathonESP32 Repository

Note: only one person in each team has to fork the repository and invite their teammates to it on Github. Everybody that wants to code including the person that forks has to clone the repo to their local computer storage!

1. Navigate to the RobotathonESP32 repository hosted on GitHub
2. Click the Fork button on the right and then click + Create a new fork
3. Change the Repository name to whatever you like
4. Click the green Create fork button at the bottom
5. Share repository access to your teammates by navigating to the settings of your newly forked repository and clicking collaborators in the left menu TODO show how to invite teammates to repository

Set Up Git SSH Authentication

This section is optional, but it will make your life easier down the road

See the official GitHub tutorial if you want more information. Otherwise just follow these instructions:

Generate SSH key

Git Bash is finicky and doesn’t support Ctrl + V for paste. Use Shift + Insert or Right Click > Paste to paste text.

1. Open Git Bash
2. Paste ssh-keygen -t ed25519 -C "your_email@example.com", change the email to the one tied to your Github account, and press Enter.
3. You will be prompted to specify a location to save the SSH key. Press Enter to specify the default location.
4. You will be prompted to enter a passcode. Press Enter twice to specify no passcode.

Note that you can add a passcode if you’d like, but it is not necessary. If you do, keep in mind that the Bash terminal does not show your passcode as you type it out. Just continue (accurately) typing and press Enter when done.

Add SSH key to SSH-agent

1. Paste eval "$(ssh-agent -s)" into the terminal and press Enter to start the SSH-agent
2. Paste ssh-add ~/.ssh/id_ed25519 into the terminal and press Enter to add your key to the SSH-agent

Add SSH key to Github

1. Paste cat ~/.ssh/id_ed25519.pub into the terminal and press Enter to display your public SSH key
2. Copy the entire key
3. Navigate to the upper-right corner of any page on GitHub, click your profile photo, then click Settings (gear icon)
4. In the Access section of the sidebar, click SSH and GPG keys
5. Click New SSH key or Add SSH key.
6. Put whatever for the title
7. Select the key type to be Authentication
8. Click Add SSH Key

Clone Forked Repository

1. Go to the your team’s newly forked repository
2. Click the green “<> Code” button
3. If you did the previous section, copy the SSH git link. Otherwise copy the HTTPS link. What is the difference?
4. Open Git Bash and navigate to where you want to keep your code for the competition (i.e. Documents, Desktop, etc.)
5. Run the following command into your Git terminal git clone https://github.com/ut-ras/RobotathonESP32.git

Install USB-UART Bridge Driver

This allows your computer to recognize and program your ESP32 when you plug it in.

1. Go to SiLabs installer webpage

Download the following file: TODO: add picture

1. Extract the downloaded zip file and run the appropriate installer application inside (likely x64)
2. Agree and use default configuration

Install 7-zip

This step is optional, but it will save you at least 30 minutes when unzipping your VSCode installation

1. Go to the 7-zip download page https://www.7-zip.org/
2. Install using default directory TODO: How to use 7-zip

Install Preconfigured VSCode

Do this even if you already have VSCode to minimize all environment setup issues. Installing the ESP-IDF extension manually may result in unecessary debugging.

1. Download zip folder from Box TODO insert box link
2. Unzip the file to your C: drive (this WILL take a while unless you use 7-zip)
3. Launch the “containerized” VSCode by running the Code.exe file in the unzipped folder
4. In the top menu bar of VSCode, click File > Open Folder
5. Open the folder where you cloned the Robotathon Git repository (should be “RobotathonESP32” by default)
6. Wait for ESP-IDF to initialize
7. Build the project by clicking the wrench icon in the bottom ribbon of VSCode (this will take a while) (TODO edit image to have circled button)

Flash your ESP32

1. Plug in your ESP32

2. Click the COM button (plug icon) in VSCode’s bottom ribbon menu (TODO edit image to have circled button)

3. In the popup dialogue at the top of VSCode, select the COM port labeled Silicon Labs

4. Click the Flash button (lightning button) in the bottom ribbon menu (TODO edit image to have circled button)

5. Select UART in the popup menu

6. Press and hold the flash enable button on your ESP32 (small black button labeled “100”) until the following output shows in your terminal:

7. Open the serial monitor (monitor/TV icon)

Note: Building and flashing after the first time does not take nearly as long. In fact, you can press the Build, Flash, and Monitor button (fire icon) to streamline the process!

macOS Setup

1) Run the Bash script named macOSInstall.sh found in RobotathonESP32/scripts 1) If that fails, then try to manually follow the steps here: good luck 😄👍 https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/linux-macos-setup.html TODO figure out what to do the setup script installs the CLI for esp-idf isntead of VSCode extension proly just gona make them go through the install manually

Install VS Code

TODO

Install Git

TODO

Install SiLabs UART-USB driver

1. Go to SiLabs installer webpage

Download the following file: TODO: add picture

1. Extract the downloaded zip file and run the appropriate installer application inside
2. Agree and use default configuration

Example Program

Here is an example program that blinks the onboard LED. “Blinky” projects are a standard “hello world” type of program that demonstrate your development environment works properly.

If you replace your arduino_main.cpp file’s contents with the following and flash properly, then your ESP32’s blue onboard LED will begin to blink (yay 😄)!

#include "sdkconfig.h"
#include <Arduino.h>

#define ONBOARD_LED_PIN 2 // defines the word "LED_BUILTIN" as the number 2 for ease of use/readability when using the pin later

void setup() {
    pinMode(ONBOARD_LED_PIN, OUTPUT); // configures pin 2 to be a GPIO output pin 
}

void loop() {
    digitalWrite(ONBOARD_LED_PIN, HIGH); // writes a digital high to pin 2
    delay(1000); // waits for 1000 milliseconds (1 second)
    digitalWrite(ONBOARD_LED_PIN, LOW); // writes a digital low to pin 2
    delay(1000);
}