Windows Setup

It is highly recommended to follow everything 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 a cloud service for saving your Git repositories online. 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 fork1.png :(
  3. Keep the repository name as RobotathonESP32 fork2.png :(
  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 6 invite teammates to my forked repository?)

Set Up Git SSH Authentication

This allows for easy and secure interfacing with Git when you want to touch your repositories. The SSH keys are a nice way to authenticate your identity with GitHub.

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. Everyone has to do this to work on code!

  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
  6. You will likely run into Git having an issue with the authenticity. Simply type yes and press Enter git_authenticity_confirm.png w=200 h=400 :(

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 VS Code and ESP-IDF Extension

VS Code is an easily customizable IDE with many extensions and a large community, meaning you can easiy find solutions to any issues that may arise :)

If your Windows username has spaces in it, then you will need to use the dropdown guide in lieu of the Normal Installation to set up your VS Code! This is because ESP-IDF cannot install properly if the installation path contains spaces, so the following is our workaround :)

🎁 Alternative Installation (Only do if you have spaces in your Windows username)

Preconfigured Installation (Only do if you have spaces in your Windows username)

The preconfigured version allows you to circumvent the issue of not being able to install ESP-IDF if your Windows username has whitespace in it (ESP-IDF refuses to install if that is the case). This is a (in my humble opinion) a better solution than creating an entirely new account on your computer

Install 7-zip

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

  1. Download zip folder from Box (~3.1 GB)
  2. Unzip the file to your C: drive using 7-zip. (How do I use 7-zip?)

This will take a while if you don’t 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 the first time) vscode_bottom_ribbon_build.png :(

Normal Installation

  1. Download and install VS Code
  2. Open the extensions tab and search ESP-IDF TODO put picture
  3. Download the ESP-IDF extension TODO put picture
  4. Open the setup wizard by clicking the Configure Extension button TODO put picture
  5. Click Express TODO put picture
  6. Check the box saying Show all ESP-IDF tags TODO put picture
  7. Select option v4.4.8 (release version) TODO put picture
  8. Ensure the installation paths are valid (i.e. no red warnings) and click the blue Install button
  9. Wait (this will take a while) :)
  10. In the top menu bar of VS Code, click File > Open Folder
  11. Use VS Code to open the folder where you cloned the Robotathon repository (“RobotathonESP32” by default)
  12. Wait for the ESP-IDF extension to initialize
  13. Build the project by clicking the wrench icon in the bottom ribbon of VS Code (this will take a while the first time) 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, build, and flash properly, then your ESP32’s blue onboard LED will begin to blink every second (yay 😄)!

Note that it is your responsibility to integrate this code with the controller starter code for the environment setup checkpoint!

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

Tip: Make sure to enable auto-save in your VS Code! It will save you a lot of headaches down the road :)