Skip to content

Embedded Setup

Jump to bottom
Dylan Brose edited this page Feb 11, 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 should start installing the PlatformIO IDE extension

Important

If VSCode doesn't automatically install the PlatformIO IDE extension, then manually install it via the Extensions tab on the left in VSCode

  1. After PlatformIO is installed, it will start configuring the project. If it doesn't, restart VSCode and re-open the project.

Important

If PlatformIO still refuses to configure the project, you will have to click its icon. It's on the left, and should be one of the bottom most icons. It looks like an alien head. Click it and wait for the project to be completely configured.

  1. This will take a while! Like, quite a while. Buckle down and wait.
  2. After everything finishes setting up with PlatformIO, you may have to completely close VSCode and re-open the project
  3. VSCode is now ready to use!

Building The Project

  1. In the root of the project files, there should be a file called env.h.schema. Duplicate this file and rename it env.h.
  2. In this env.h file, you have to fill in some information. The WiFi SSID and Password will be provided to you by the Project Manager.
  3. Connect to the network with your computer after filling in the details (The WiFi name is the SSID).
  4. Now get your local IP Address. On Windows, this can be done by typing ipconfig in a command prompt, and copying the IPv4 Address from the Wireless LAN adapter Wi-Fi: section

Note

If you have your own 2.4GHz network, you may provide your own details and connect to that network instead

  1. After filling in your ip address, you are ready to build the repo.
  2. You can do this by clicking the checkmark icon at the bottom of VSCode. Hovering over it will show the label PlatformIO: Build.

Flashing The ESP

  1. First, check what COM ports are showing on your computer. You can do this through VSCode by clicking the Plug icon at the bottom of VSCode with the word Auto next to it. Hovering over it will show the label Set upload/monitor/test port.
  2. Read through and memorize what COM ports show up in the dropdown near the top.
  3. Now plug in the ESP (If the ESP is connected to a bot, refer to the notice below).
  4. Press the Plug button again after a few seconds, and click the new COM port that shows up in the dropdown.

Important

If the COM port refuses to show up, you may have to put the ESP into Download Mode. There are two buttons on the ESP, RST (Reset) and 0. Hold down 0 and press RST. You can now let go of 0. After a short while, the COM port should now show up.

  1. Now you can click the right arrow icon on at the bottom of VSCode. Hovering over it will show the label PlatformIO: Upload.

Important

If you had to put the ESP into Download Mode, you must now short press RST to run the program after uploading.

Warning

If the ESP is connected to a bot, do not plug it into your computer unprotected! This is because the ESP is being powered by the batteries, and power can flow through the ESP back into your computer. To prevent this, you must use a special data-only cable (This is the yellow cable in the ChessBots cabinet). Make sure the switch is set to BLACK! Red is DANGER.

Monitoring The ESP Serial Output (Logging)

  1. To monitor the serial port, you will need the Serial Monitor extension if you don't already have it.
  2. After it's installed, you can use it by opening a VSCode terminal. You can go about this in two ways.
  3. Either go to the View button at the top of VSCode, then navigate View->Terminal. You can also press Ctrl+Shift+~ to open a new terminal.
  4. After opening a terminal, go to the terminal window at the bottom and click the Serial Monitor Tab.
  5. Select the correct COM port, then click Start Monitoring.
  6. After a few seconds, you should start seeing a message being printed that says the ESP failed to connect to the server. This is because you don't have the server setup.
  7. If you haven't set up the ChessBots Server, and you want to, follow this ChessBots Server Setup Guide.

Note

You can also just use a server running on someone else's computer. Make sure their IP is set in env.h instead of yours.

Clone this wiki locally