# PlatformIO Setup

The PlatformIO extension can be installed in VSCode. The extension also needs an installation of Python 3.6 or above. 
The virtualenv module (venv pypi package) must be available as well.

Forcing PlatformIO to use a different Python installation other than the system installed is tricky. 
PlatformIO **does not work** with a conda Python environment. The workaround is to use a portable Python build from [python-build-standalone](https://github.com/indygreg/python-build-standalone) project.

Using pip from portable Python, install the platformio package as

```
pip install platformio
```

Now open VSCode and Install the PlatformIO extension. 
Once installed open VSCode user settings, search for PlatformIO and use the following options:

Use a built-in PlatformIO Core: Untick
Use a portable Python3 interpreter if available: Untick
Custom Path: (Edit in settings.json)

The corresponding settings.json file looks like
```
"platformio-ide.customPATH": "/home/ubuntu/python3.11-pio/python/bin/",
"platformio-ide.useBuiltinPython": false,
"platformio-ide.useBuiltinPIOCore": false,
```

Restart VSCode after and PlatformIO should work.

## Other Issues

PlatformIO Home does not open when using the PlatformIO extension from a remote VSCode setup (like `code tunnel` or VSCode server).
This is because the extension tries to connect to the PlatformIO core web server started on localhost on opening the PIO home page. When VSCode is accessed remotely the localhost from the web browser's context is not the same as the localhost of the system where PlatformIO core is installed.

In such cases use the PlatformIO Core CLI to create a new project from the command line and open the folder in VSCode instead.

Example
```
 mkdir my-esp32-project
 cd my-esp32-project
 pio project init --board esp32doit-devkit-v1
 ```
 
 The list of available boards can be found by running `pio boards <boardname>` (`pio boards esp32`) and at https://docs.platformio.org/en/latest/boards/index.html.
 
 More details: https://docs.platformio.org/en/stable/core/quickstart.html
 
 Then open the directory my-esp32-project in VSCode to continue development. PlatformIO will recognize the project as usual.
 
 ## Compiling from the CLI
 
 The CLI gude can be found at: https://docs.platformio.org/en/stable/core/userguide/index.html
 
 ```
 pio run
 ```
 
 Use the `-v` / `--verbose` argument for the detailed commands being run
 
 ## Cleaning build files
 
 ```
 pio run --target clean
 ```
 
 or `pio run -t clean -v`
 
 ## Uploading build files without compiling
 
 This is useful when we do not want to distribute the source code of the firmware. 
 We can delete the source directories (include/, lib/, source/, test/) and keep the other directories including the .pio directory.
 Then in the project folder
 ```
 pio run -t nobuild -t upload
 ```
 
 which will upload the compiled firmware directly.
 
 - https://community.platformio.org/t/simple-utility-to-field-upload-firmware-bin-without-the-ide/22153
 - https://community.platformio.org/t/compile-and-save-file-for-future-upload/21266
 - https://community.platformio.org/t/upload-latest-build-without-a-compile-link/9520
 - https://community.platformio.org/t/compile-and-save-file-for-future-upload/21266