Windows Setup

It is highly recommended to follow each component installation in order!

Install Git

This is a source-control application that is very useful for sharing projects with many files.

  1. Go to the Git website
  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

GitHub is like a Google Drive for your Git repositories. Go to the GitHub website and create an account if you do not have one already.

Fork RobotathonESP32 Repository

Forking a repository creates a copy that you control on your GitHub account. Teams will use our RobotathonESP32 repo as the template.

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. Go to the ut-ras RobotathonESP32 repository hosted on GitHub
  2. Click the Fork button on the right and then click + Create a new fork my_image.png :(
  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 (How do I invite teammates to my forked repository?)

Set Up Git SSH Authentication

This SSH section is optional, but it will make your life easier down the road by letting you push code to your remote repository without manually typing credentials

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 (keep the quotes), 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 likely be prompted to enter a passcode. Press Enter twice to specify no passcode.

You can add a passcode if you’d like, but it is not recommended. 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

The key should look something like ssh-ed25519 SFNJNAFNEJKFNJNJKNFJHFJAHOHiowuroiuwr/sfjeher+KX/rH email@gmail.com

  1. Navigate to the upper-right corner of any page on GitHub, click your profile photo, then click Settings (gear icon) my_image.png :(
  2. In the Access section of the sidebar, click SSH and GPG keys
  3. Click the green New SSH key button on the right my_image.png :(
  4. Put whatever you want for the key title name
  5. Select the key type to be Authentication
  6. Paste in the key you copied earlier into the Key section
  7. Click Add SSH Key

Clone Forked Repository

Cloning is the process of copying a Git repository onto your local computer storage

  1. Go to your team’s newly forked repository my_image.png :(
  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? my_image.png w=200 h=400 :(
  4. Open Git Bash and navigate to where you want to keep your code for the competition, such as your Documents or Desktop. How do I do that?
  5. Run the following command in your Git terminal: git clone [PASTE GIT LINK HERE] without the square brackets

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
  2. Download the file named CP210x Windows Drivers
  3. Extract the downloaded zip file and run the appropriate installer application inside (likely x64)
  4. Agree and use default configuration

Install 7-zip

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

7-zip is a file compression tool that works much faster than your native Windows tools.

  1. Go to the 7-zip download page
  2. Install using defaults
  3. Launch 7-zip

Install Preconfigured VS Code

VS Code is an easily customizable IDE with many extensions and a large community. The preconfigured version you will download will already have ESP-IDF installed.

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

  1. Download zip folder from Box
  2. Unzip the file to your C: drive

This will take a while unless you use 7-zip. How do I use 7-zip?

  1. Launch the “containerized” VS Code by running the Code.exe file in the unzipped folder
  2. In the top menu bar of VS Code, click File > Open Folder
  3. Use VS Code to open the folder where you cloned the Robotathon repository (“RobotathonESP32” by default)
  4. Wait for the ESP-IDF extension to initialize
  5. Build the project by clicking the wrench icon in the bottom ribbon of VS Code (this will take a while) vscode_bottom_ribbon_build.png :(

Flash your ESP32

  1. Plug in your ESP32

  2. Click the COM button (plug icon) in VS Code’s bottom ribbon menu vscode_bottom_ribbon_com.png :(

  3. In the popup dialogue at the top of VS Code, select the COM port labeled Silicon Labs COM_port.png :(

  4. Click the Flash button (lightning button) in the bottom ribbon menu vscode_bottom_ribbon_flash.png :(

  5. Select UART in the top popup menu UART_selection.png :(

  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) my_image.png :(

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!

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 😄)!

Note that it is your responsibility to integrate this code with the controller starter code!

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

#define ONBOARD_LED_PIN 2 // defines the word "LED_BUILTIN" as the number 2 for readability

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);
}