Visual Studio Code with Arduino - ESP8266

The Arduino IDE is awesome for getting small projects up and running really quickly, but as soon as your project starts to get a little more complex and you are creating and managing more than a handful of files it gets painful pretty quickly.

Visual Studio Code is an alternative IDE you can use not only to edit your projects, but also build, upload and even debug your project! It comes with benefits like Intellisense, Git integration and easy navigation to definitions.

I followed this guide to get started, but there were a few little things that tripped me up I thought I'd give some more detailed examples.

1. Get yourself setup with Visual Studio Code

Download and install VS Code for your OS. I'm using a Mac for this, I haven't tried with Windows/Linux but process should be the same.

2. Install the Arduino plugin

Install the VS Code plugin for Arduino from the VS code store. Take note of the recommended version of Arduino to install (required for Step 3).

3. Install the Arduino IDE

VS Code will use the Arduino to actually build your project. Take note of the Arduino version comment in the VS code arduino plugin and select an appropriate version to download.

4. Open your project

Use the file->open (not "open workspace") to open the root folder of your project.

5. Configure your settings

Add any special boards you want to the project config. In my case I've added the esp8266 boards.

Menu -> Code -> Preferences -> Workspace Preferences Tab -> Type "additionalUrls" in the search bar and "Edit in settings.json" the file.

Add the following so your settings.json file looks something like this:

{
"arduino.enableUSBDetection": false,
"arduino.additionalUrls":"http://arduino.esp8266.com/stable/package_esp8266com_index.json"
}

6. Set your Arduino board

Set the board for your project either from the drop down menu at the bottom of the screen or by navigating to the command options using cmd + shift + p, then searching for "Arduino" commands and select the "Arduino: Change Board Type". 

It can take a while for this to load sometimes, be patient. It took around a minute the first time I opened it for my project. Sometimes my board configuration screen is black as I've shown below

7. Initialise the project

Ctrl+Shift+P and then search for "Arduino" commands, scroll down to "Initialise" and hit it. This will add a arduino.json and c_cpp_properties.json files to your project and set up a few things. Add any project dependencies here.

8. Compile your code

Compile with the shortcut Command+Option+r, or by searching for the Arduino compile option with Ctrl+Shift+P.
You will see the Arduino logo pop up during the compilation step.

9. Upload your code

Upload with Command+Option+U

Troubleshooting

Its worth calling out that Arduino doesn't behave as you would expect with included files/folders.
Even though the VS Code IDE will be able to find a file/folder because you have linked it there is a chance it still may not compile.

Take a read through the expected Arduino project file structure here and organise your project to suit.