# Using VSCode
*Experimental support for VSCode*.
1. [Pre-requisites](#pre-requisites)
1. [Configuration](#configuration)
1. [Building](#building)
1. [Flashing](#flashing)
1. [Known Issues](#known-issues)
   1. [arduino-cli.yaml](#arduino-cliyaml)
   1. [Defines specific to boards](#defines-specific-to-boards)
   1. [Intellisense](#intellisense)
   1. [Folder name must match .ino filename](#folder-name-must-match-ino-filename)

## Pre-requisites
- arduino-cli, from https://arduino.github.io/arduino-cli/
- Microsoft [VSCode](https://code.visualstudio.com/download), with the following extensions
  - Arduino
  - C/C++
  - C/C++ Extension Pack
  - C/C++ Themes (optional ??)
  - Espressif IDF (for compilation problemMatcher, and maybe more??)

## Configuration
- Edit the file `.vscode/settings.json` and modify the following variables to match your development environment:

|Setting name|Description|
|------------|-----------|
|ota-password|Password for Over-The-Air updates|
|ota-host|Hostname or IP address for OTA updates|
|ota-port|Port for OTA updates|
|arduino-esp32-version|Version of Arduino package `esp32:esp32`|
|arduino-cli-location|Full path to `arduino-cli.exe` / `arduino-cli`|
|arduino-cli-fqbn|ESP32 FQBN, such as `esp32:esp32:esp32wrover`|
|arduino-cli-compile-flags|Your own *define* compilation flags, such as `-DADD_YOUR_COMPILE_FLAGS`|
|arduino-cli-build-output|Arduino build output location, such as `${workspaceFolder}\\build_output`|
|arduino-esp32-include|Relative-to-AppData location to ESP32 Arduino include folder root|
|esp-tool-location|Full path to `esptool.exe` (Windows) / `esptool` (Linux)|
|cpp-compiler-location|Path to Arduino compiler to use|

## Building
Just hit `[Ctrl-Alt-b]`, which is the default keyboard shortcut in VSCode to *build* a project.

## Flashing
To flash / upload the compiled project to the board, *Tasks* have been defined in `tasks.json`.
To run a task, hit `Ctrl-p [space]` and the following *Tasks* will be available to chose from.

*TIP*: Find your preferred method, such as OTA Upload, and set a keyboard shortcut such as `Ctrl-Alt-9` which is unused by VSCode by default.

|Task name|Description|
|---------|-----------|
|Compile  |Same as hitting `[Ctrl-Alt-b]` or _Verify_ in Arduino IDE|
|COM Upload App only|Upload via UART, but only the application binary (faster, but not always 100% working), not sure why.|
|COM Upload with partitions|Upload all partitions via UART, including the app. Stable method to upload via USB.|
|OTA Upload|Over The Air Upload. Stable.|
| | |

## Known Issues
### arduino-cli.yaml
It is unclear whether the content of this file has any impact whatsoever.

### Defines specific to boards
At the moment, `.vscode\c_cpp_properties.json` contains a massive `defines` array which was automatically generated by the _Arduino VSCode Extension_ itself, *for my board only*. 
You may have to replace the array with the values respective to your own ESP32 board.
### Intellisense
There seems to be variable replacement issues with Intellisense.
At the moment, in `.vscode\c_cpp_properties.json`, trying to replace this:
```
    "arduino-esp32-version": "2.0.14",
    "arduino-esp32-location" : "Arduino15\\packages\\esp32",
    "arduino-esp32-include" : "Arduino15\\packages\\esp32\\hardware\\esp32\\${config:arduino-esp32-version}",
```
with a more simplied version such as this:
```
    "arduino-esp32-version": "2.0.14",
    "arduino-esp32-location" : "Arduino15\\packages\\esp32",
    "arduino-esp32-include" : "${config:arduino-esp32-location}\\hardware\\esp32\\${config:arduino-esp32-version}",
```
.. in order to reuse `arduino-esp32-location` in other configuration values will result in Intellisense not finding, among others, `Arduino.h`. 
### Folder name must match .ino filename
While it would make sense to rename `src.ino` to something like `HomeSpanDemo.ino`, doing so will fail in
building the project. An error like the following will occur:
```
Can't open sketch: main file missing from sketch: C:\Users\JohnDoe\Documents\HomeSpan\src\src.ino
```
There seems to be a limitation where the `.ino` base filename has to match the folder name it is in.
Meaning if we'd want to use `HomeSpanDemo.ino`, the folder name the file is in would have to be
renamed from `src\` to `HomeSpanDemo\`.