Skip to content

Embedded Setup

Jump to bottom
Dylan Brose edited this page Feb 10, 2025 · 12 revisions

Setting up your Environment!

By following this guide, you should be able to have all of the necessary software required for working on the ChessBot Embedded Software!

Note

There may be differences in the setup process for Windows, Linux, and Mac. Overall, both processes will be very similar.

Software Required

  • Git
  • Text Editor (VSCode)
  • Platform IO (VSCode Extension)
  • Python

Software Installation

Git

Git is the software that allows users to collaborate with their code! Having this allows you to pull the latest version of the ChessBots Repositories onto your computer. If you already have Git installed, you can bypass this step. If you aren't sure, follow along. The simplest way to ensure Git is set up properly is to use a client like GitHub Desktop. This is how we will install moving forward.

  1. Create an account at Github.com

Tip

If you already have an account, you can use your existing one

  1. Download GitHub Desktop for your system (Download Here!)
  2. Open the installer and proceed with the install process.
  3. When prompted, log in with your GitHub account.
  4. Choose to allow GitHub to configure Git. Do not configure manually.
  5. If you are on MacOS, when prompted, allow GitHub Desktop to be moved to the Application folder.
  6. Done!

VSCode

VSCode is simply a text editor with a lot of great features for software development, such as powerful extensions, syntax hinting, and Git integration. This is what we recommend for all ChessBots development for its ease of use. If you want to use another text editor, you may have a more difficult time moving forward since some of our extensions may not be compatible.

  1. Download VSCode (Download Here!)
  2. Proceed with install process

Note

If you are using MacOS, make sure to move to the application folder! It is not automatic for VSCode!

  1. Done!

Python

Python is required for PlatformIO, the software that allows us to upload code to a ChessBot's MicroController.

  1. Download Python Installer (Download Here!)
  2. Proceed with install process
  3. Done!

Environment Setup!

Now that all the software is installed, we can setup our environment for ChessBots! The way I describe is my personal preference, so you can make some changes along the way if preferred. For simplicity, feel free to follow my steps exactly.

Making a dev folder

Having a dev folder is important. This is a location where git can pull your projects to, and a central location for all of your development work. It is important to avoid syncing your code in a cloud location, such as OneDrive, iCloud, Google Drive, Box, or Dropbox. This can cause issues when working with git, and should be avoided! Instead, backup your files the old fashioned way with an external drive, or make sure your work is pushed to Git.

Windows

  1. Open Explorer
  2. In the Explorer Address Bar, navigate to C:/Users
  3. Choose your user folder
  4. Create a new folder called "dev" in your user folder.

Warning

Saving your dev folder to Desktop or Documents is risky. These locations may be synced by Onedrive on your system, which can cause damage!

MacOS

Setting up a dev folder on MacOS is simple!

  1. Open Finder
  2. Click "Go" at the top of the screen
  3. Click "Home"
  4. This will open your home folder, you should see things like "Downloads" and "Pictures" in here
  5. Create a new folder called "dev" in the home folder.

Warning

Saving your dev folder to Desktop or Documents is risky. These locations may be synced by iCloud on your system, which can cause damage!

Pulling The ChessBots Embedded Repo

Now, we need to pull the latest version of the ChessBots Embedded code to our computer. For this, we will use Github Desktop. If you prefer to use the command line, feel free, we will not be explaining that in this guide.

  1. Open GitHub Desktop
  2. In your web browser, navigate to ChessBots Embedded Repo (Click Here!)
  3. Click the green "Code" button
  4. Click "Open with GitHub Desktop" and accept the prompt.
  5. GitHub Desktop will open with the project.
  6. Type in the correct folder, for macOS, that looks like this:

Important

Make sure to include the /chessbots-embedded at the end. This will create a chessbots-embedded folder for the project.

  1. Done! You now have the ChessBots Embedded Source Code on your system!

Setting up VSCode

Our last step is to setup VSCode for the project.

  1. Open VSCode
  2. Select "Open Folder" and choose the chessbots-embedded folder located in "dev"
  3. VSCode will prompt you to install the recommended extensions, click yes.
  4. This will take a while!
  5. After everything finishes setting up with PlatformIO, restart VSCode.
  6. VSCode is now ready to use!

First Time Setup

  1. Open this folder in Visual Studio Code.
  2. Create a file env.h in the root folder of the project and initialize it with the environment-specific information using this template: 
    // Put your IP here and uncomment if you aren't on the special router
//#define FIXED_SERVER_IP "10.0.0.1"

// Comment this out if you have a working OTA router
#define OTA_UPDATE_OPTIONAL

// Uncomment this when you are testing your binary image in the emulator
// #define WOKWI_COMPAT

#ifdef WOKWI_COMPAT
#define WIFI_SSID "Wokwi-GUEST"
#define WIFI_PASSWORD ""
#else
#define WIFI_SSID "ChessBot"
#define WIFI_PASSWORD ""
#endif

/*
router-ssh-user=admin
router-ssh-password=

binary-location=build
esp32-serial=

do-build=false
*/
  3. Open the extensions tab on the left (4 squares).
  4. Install the ESP-IDF and Serial Monitor extensions.
  5. Choose "EXPRESS" installation after it finishes installing.
  6. Set "Select ESP-IDF version" to "v5.3 (release version)" and click "Install".
  7. Plug the target S2 Mini into your computer.
  8. Press the RST button on the S2 Mini while holding the 0 button. This puts the ESP32 into bootloader mode and allows it to be flashed manually.
  9. Run the command "ESP-IDF: Select port to use" and select the port with "usb" in it.
  10. Run the command "ESP-IDF: Select Flash Method" and select "UART".
  11. Run the command "ESP-IDF: Build, Flash, and start a monitor on your device".
  12. You should see an error about the flash failing. To verify it worked, enter the Terminal tab and it should say the flash reached 100%. If it didn't, you likely picked the wrong serial port or didn't enter the bootloader.
  13. Press the RST button on the S2 Mini to reboot into your new firmware.
  14. Open the "SERIAL MONITOR" tab in the terminal modal (should be to the right of "TERMINAL").
  15. Select the serial port for the S2 Mini and click "Start Monitoring".
Clone this wiki locally