Arduino Development using VSCode

The Arduino IDE provides a means to write code for microcontrollers, with library management, compilation and uploading of your code. But the code development environment is lacking many of the features of a modern IDE. Enter VSCode to the rescue! Providing syntax checking, auto-indentation (with clean up), and code completion via the IntelliSense feature. VSCode is free and provides a capable development environment which supports multiple languages, remote code development over SSH and many other capabilities via a comprehensive library of extensions. In this article, we will be looking at options to use it to develop code for Arduino (and Arduino supported boards).

Before starting with VSCode, you need to install the Arduino Desktop IDE (at time of writing this was v1.8.13). You can download it from www.arduino.cc/en/main/software. The VSCode extensions use the Arduino IDE under the hood, so you need this to be working with your boards.  Check that example sketches can be compiled and deployed onto your board using  the Arduino IDE. 

Now we can set up VSCode. You can download the editor from code.visualstudio.com/

We will be writing C/C++ code for Arduino, so we need to install the extension to add support for this language. 

Down the lefthand side of the VSCode window is a vertical toolbar. Click on the Extensions button to open the extensions manager. 

Find and install the C/C++ extension:

There are two options to add support for Arduino development. The more obvious looking one is the Arduino extension. I was able to get this working with some configuration required, but a number of features did not work for me. I could not open the Serial Monitor, Teensy boards were not supported and I found the IntelliSense feature reported problems in my code which were not problems for the Arduino compiler. I did learn a few tricks to make things workable and I have detailed these at the end of this article if you want to use this extension. But I found things worked better for me using the alternative option, the PlatformIO IDE extension. You probably don't want to install both as the IntelliSense feature configurations of each are not compatible.

PlatformIO IDE

The PlatformIO IDE extension provides support for more boards (including the Teensy family), but it is not as tolerant of the non-standard C/C++ syntax which Arduino sketches allow. You will need to convert any .ino files into .cpp files in your projects to work with this extension. You will also find that functions have to be declared before they are used, and global variables and functions declared in one file in a project will not be in scope in other files. More details on this later, but aside from these code compatibility issues I found it very easy to set up and most of the configuration was automatic.

To get started with the PlatformIO IDE, I suggest you follow their quickstart guide. That is what I did, and there is little point in me repeating that information here. See https://docs.platformio.org/en/latest/integration/ide/vscode.html#quick-start 

Once I had built a basic blink sketch following the quickstart guide, I successfully imported an existing Arduino project from the extension home page, ticking the option to use the Arduino libraries already installed on my computer. This created a copy of the project under my <user>/Documents/PlatformIO/Projects directory, with the configuration set up to include libraries from the existing Arduino IDE installation on my computer. You select the board you want to compile for in the import dialog. I already had the Teensyduino packages installed, and found the Teensy boards listed in the board picker. The IDE warned me that I should change the .ino file to a .cpp file in order for IntelliSense to work. The project source was also put under a 'src' folder. Projects with both cpp and header files should be reorganised by moving the h files from the src folder into the include folder. I just renamed my single ino file through the VSCode explorer pane and I was able to compile and upload the project to my Teensy 3.2 board.

One additional configuration change I made was in the platformio.ini file under my project. I added a build_cache_dir line as follows in my ini file. You can point this to any folder you like outside your project. By doing this, libraries compiled as part of your sketch will not need recompiling every time you rebuild. So after the first build, subsequent builds will only need to recompile classes with code changes, which will be faster.

[platformio]

; Set a path to a cache folder

build_cache_dir = C:/temp/PlatformIO_buildcache

You can also add additional library paths in this file. I was working on a project which uses a library I am also developing on my computer. So I added a path to my library code in development after the path to the Arduino libraries (note the syntax ~ to refer to your user home directory):

[env:teensy31]

platform = teensy

board = teensy31

framework = arduino

lib_extra_dirs = 

    ~/Documents/Arduino/libraries

    ~/Documents/dev/Cpp/RGBMatrixAnimations

That was all I needed to do to get up and running with simple single file sketches. But to make multi-file projects compatible I needed to make some code changes. The Arduino IDE does some rewriting of your code before it compiles it. All .ino files in the project are essentially combined into one large code file, and any functions defined in them have declarations added to the code before they get called. You do not get any of this in PlatformIO. This does force you to write more standards compliant code though, so it is no bad thing. To get my more complex project to compile I had to do the following:

1. All .ino files in a project need to be changed to the extension .cpp
2. Functions defined in my main cpp file needed to either be defined before they are called, or have forward declarations added near the top of the file. (This article explains it in more detail: https://community.platformio.org/t/order-of-function-declaration/4546/2 ).
3. To call any code in other .cpp files requires an include for that .cpp file adding to the file calling that code. This also means you need to add includes for any library header files to all the cpp files which use those libraries (rather than just once in the main project code file).
4. Global variables declared in the main code file can no longer be accessed from code in other files. So you'll need to pass them to the code using them in other files (either via class constructors or as parameters to any methods).

I avoided declaring functions directly in secondary cpp files, instead using these files only for class declarations. You can then pass variables to these classes via their constructors, or setter member methods. This gives tighter scope control and makes for more robust code. Overall I found the PlatformIO extension worked better for me than the Arduino extension, but if you want a more Arduino like coding experience rather than standards compliant C++ then you may find the Arduino extension suits you better.

Arduino Extension

If you want to use the Arduino extension instead of PlatformIO (maybe you want to work on projects with .ino files for example), then install that extension instead.

This adds several Arduino commands to the command palette. With this installed, when you open an Arduino sketch (.ino) file in VSCode you should see a custom footer bar with clickable options to select the connected board, COM port and Programmer (if you are using one). Click on the <select board> item and the board manager should open (you can also open it via the Command Palette). I found the <select PORT> command was not working, so I had to set it manually in the arduino.json file. Open this file from the .vscode folder in your workspace, and add the COM port line as follows (setting the correct numbered COM port matching the one you used to program your board from the Arduino IDE).

"port": "COM4",

You should now be able to verify sketches and upload them to your board using the Arduino commands.

Open Command Palette (Ctrl + Shift + P), and type 'Arduino' to filter the commands list in the command picker. You will see 'Arduino: Verify' and 'Arduino: Upload' commands. Note these also have keyboard shortcuts displayed. e.g. You can compile and Upload the open sketch using Ctrl + Alt + U.

The first time you do this for a project, you will be asked which .ino file is the main one (if you have more than one in the sketch). Once you select this it is added into the arduino.json configuration file (so you know where to go to change it if you change the main file later).

You may see a warning at the start of the compiler output, saying 'Output path is not specified. Unable to reuse previously compiled files. Upload could be slow. See README.'. This means that each time you make a code change and go to upload again, the compiler has the recompile the entire project including all libraries, which can take a long time. To allow it to reuse the output from a previous compile and only recompile the files which have been changed, you need to define and output folder in the arduino.json file. This folder should not be under the project folder. You can add the following line to set the output to a folder named ArduinoOutput located alongside your project. Alternatively give a full path to a folder, maybe in your temp directory.

    "output": "../ArduinoOutput",

This should get you to the point where you can open, edit, compile and upload sketches to your boards. But you may notice the code IDE still shows lots of errors in the code because the VSCode IntelliSense feature does not know where all the Arduino libraries are located. We need to add these to the workspace include paths:

Using the command palette, run the command: C/C++: Edit Configurations (UI)

This will open the UI to edit your C/C++ configuration. You can edit your win32 configuration, or create a new one. I decided to create a new one named 'arduino'.

In the 'Include Path' field, make sure all 3 of these paths are added in addition to the workspaceFolder item:

${env:userprofile}/AppData/Local/Arduino15/packages/**
${env:userprofile}/Documents/Arduino/libraries/**
C:/Program Files (x86)/Arduino/hardware/arduino/avr/libraries/**

That last one assumes you installed the Arduino IDE into the default location under C:\Program Files (x86)\Arduino. If you installed to a different location then change it as appropriate. Note the use of the userprofile environment variable to make the configuration work on any computer. These configuration files can be checked into source control so that your projects can be checked out and run quickly on different computers regardless of the logged in username.

My complete arduino configuration section looked like this:

        {

            "name": "arduino",

            "includePath": [

                "${workspaceFolder}/**",

                "${env:userprofile}/AppData/Local/Arduino15/packages/**",

                "${env:userprofile}/Documents/Arduino/libraries/**",

                "C:/Program Files (x86)/Arduino/hardware/arduino/avr/libraries/**"

            ],

            "defines": [

                "_DEBUG",

                "UNICODE",

                "_UNICODE"

            ],

            "compilerPath": "C:\\Program Files (x86)\\mingw-w64\\i686-8.1.0-posix-dwarf-rt_v6-rev0\\mingw32\\bin\\gcc.exe",

            "cStandard": "gnu18",

            "cppStandard": "gnu++14",

            "intelliSenseMode": "gcc-x64"

        }

Finally, open the command palette again and run the command C/C++: Select a configuration, and select the 'arduino' configuration. This should clear most of the reported 'problems' in the code IDE, and IntelliSense code completion suggestions should now be working. There are some exceptions to this however.

The Arduino IDE appears to treat all .ino files in a project directory as being part of the main .ino file. So any code split across different .ino files will be compiled by the Arduino IDE as if that code was all in one big file. However the VSCode IntelliSense environment does not do this. One way to avoid this problem is to only have a single .ino file in your project, and use the extension .cpp for any other code files. You will then have to add #include statements as required to include these .cpp files in other files which reference them, and you will no longer be able to access globals defined in the main .ino file from code in the .cpp files. It will make you write better code, forcing references to be passed to objects rather than being accessible everywhere via globals. But you may find projects published by others do not work with the IntelliSense feature in VSCode.

In some cases, libraries will have been written to be compatible with both Arduino and Windows/Linux C/C++ programs. These can cause problems because the VSCode IntelliSense environment does not realise it is running in an Arduino environment. So it tries to check the code against windows libraries which will not be on your Arduino project path. You can make it behave like an Arduino environment by adding the following line to the start of your main sketch .ino file:

#define ARDUINO 100

But I suggest commenting out the line before compiling as the Arduino IDE will set it's own define, which may be different to this. Better to just live with these reported include errors since they will not apply when the Arduino IDE compiles the code.

Some data types in my project were flagged as not defined by default in standard C/C++. These included:

• byte
• boolean
• uint8_t/uint16_t/uint_32_t

If you want to avoid these being flagged as errors by IntelliSense then you can use bool in place of boolean, uint8_t in place of byte. Then to make IntelliSense aware of the uint types, I added the following #if defines which I use in code designed to be compatible with both Arduino and non-Arduino environments:

#if defined(ARDUINO) && ARDUINO >= 100

#include "Arduino.h"

#elif defined(ARDUINO)

#include "WProgram.h"

#else

#include <stdint.h>

#include <stdio.h>

#endif

I am not sure how much of this was really needed, as the IntelliSense appeared somewhat temperamental about which errors it reported. Sometimes if would just be complaining that included libraries referenced header files it could not find, but then it would suddenly report most of my file contained errors.

I was unable to get the serial monitor working under the Arduino extension. When I clicked the icon in the footer toolbar to open it, I saw the following error: .vscode\extensions\vsciot-vscode.vscode-arduino-0.3.2\out\node_modules\usb-detection\build\Release\detection.node is not a valid Win32 application.

I uninstalled the Arduino extension after I discovered the PlatformIO IDE extension, which appears to be working much better for me. If you have more success then please share in the comments.