macOS Setup

https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/installation.html

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 VS Code extension proly just gona make them go through the install manually

Install VSCode

Download VSCode from the online download for Mac

Installing Git

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

  1. Open the Terminal and type

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

and press enter. This will make it extremely easy to install Git.

  1. Enter brew install git to install Git

  2. 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.

Note that 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 VCP Mac OSX Driver
  3. Extract the downloaded zip file and open the installer
  4. Agree and use default configuration

Install ESP-IDF Extension

  1. Click the Extensions icon in VSCode and type ESP-IDF in the search bar
  2. Click the ESP-IDF extension and click Install
  3. Click the new ESP-IDF: Explorer icon, click Advanced in the side menu, then click Configure ESP-IDF Extension

my_image.png :(

  1. Select Express
  2. For ESP-IDF Version, select v4.4.8 and for Python Version, select the one ending in python3. Leave everything else as default.

my_image.png :(

  1. Select Install

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