PlatformIO Guide
==================

Setting Up PlatformIO
------------------------

1. Install Visual Studio Code (VS Code) from the official website: `https://code.visualstudio.com/`_.
2. Open VS Code and navigate to the Extensions view by clicking on the square icon on the left sidebar or pressing `Ctrl+Shift+X`.
3. Search for "PlatformIO IDE" in the Extensions marketplace and click "Install" to add it to your VS Code environment.

Opening a project in VS Code
-----------------------------
1. Launch VS Code.
2. Click on "File" in the top menu and select "Open Folder...".
3. Navigate to the directory where your PlatformIO project is located and select it. Click "Select Folder" to open the project in VS Code. The most common repo we use in PlatformIO is the ``motion`` repo, which contains the code for the Teensy 4.1 motion controller.

PlatformIO Project Structure
-----------------------------

+---------------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Directory/File**  | **Description**  | **Purpose**                                                                                                                                                                                                                                                                 |
+=====================+==================+=============================================================================================================================================================================================================================================================================+
|| **src/**           || Source Code     || Contains the main source code files for the project. This is where you will write your application logic and implement the functionality of your project.                                                                                                                  |
|| **include/**       || Header Files    || Contains header files that declare functions, classes, and variables used in the source code. These files are included in the source code to provide declarations and definitions.                                                                                         |
|| **lib/**           || Libraries       || Contains external libraries that your project depends on. We don't use this directory much, but it can be used to include third-party libraries that are not available through the PlatformIO Library Manager.                                                             |
|| **platformio.ini** || Configuration   || The main configuration file for the PlatformIO project. It defines the project settings, such as the platform, board, framework, and library dependencies. This file is essential for building and uploading your project to the target hardware.                          |
|| **.pio/**          || Build Artifacts || This directory is automatically generated by PlatformIO and contains build artifacts, such as compiled object files, firmware binaries, and other intermediate files created during the build process. You typically do not need to interact with this directory directly. |
+---------------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

PlatformIO Configuration File
-----------------------------

Also called Platform.ini, this file is crucial for setting up your project. It specifies the platform, board, framework, and library dependencies. Here's a breakdown of the key sections in the `platformio.ini` file:

.. code-block:: ini
    [env:teensy41]
    platform = teensy
    board = teensy41
    framework = arduino
    lib_deps =
        # List of libraries your project depends on, e.g.:
        # Adafruit GFX Library
        # Adafruit SSD1306
        # Add any other libraries you need here

This example file is for a teensy 4.1. 

- Platform specifies the microcontroller family (teensy).

- Board specifies the specific board you are using (teensy41).

- Framework specifies the software framework you are using (arduino).

- Lib_deps lists the libraries that your project depends on. You can add any libraries you need for your project here, and PlatformIO will automatically download and include them during the build process.


Building and Uploading Your Project
------------------------------------

1. Navigate to the "PlatformIO" tab in the left sidebar of VS Code. (The icon looks like an alien head).
2. In the PlatformIO sidebar, click on "Build" to compile your project. This will generate the necessary firmware binary for your target hardware.
3. Once the build process is complete, click on "Upload" to flash the compiled firmware onto your target hardware. Make sure your device is connected to your computer via USB and properly configured in the `platformio.ini` file.

.. tip:: For Troubleshooting:

   If for some reason your computer has multiple microcontrollers connected, you may need to specify the correct port in VSCode. There's a small icon in the bottom left of the VSCode window that shows the current port. Click on it to select the correct port for your device. (It looks like a pl)