search

microsoft / vscode-arduino

Visual Studio Code extension for Arduino
Other
1.17k stars 225 forks source link

readme

Visual Studio Code extension for Arduino (deprecated)

⚠️ Warning ⚠️

This extension is deprecated and no longer maintained. We recommend existing customers to use the Arduino IDE software.

This extension will no longer be available on the marketplace as of 10/1/2024, please see details here.

Gitter

Welcome to the Visual Studio Code extension for Arduino preview ! The Arduino extension makes it easy to develop, build, and deploy your Arduino sketches in Visual Studio Code, with a rich set of functionalities. These include:

Prerequisites

Either the legacy Arduino IDE or Arduino CLI are required. The recommended approach is to use the version of Arduino CLI that comes bundled with the extension, which works out of the box. Support for the legacy Arduino IDE will be removed in a future version of the extension.

Arduino CLI

To use the bundled version of Arduino CLI, arduino.useArduinoCli should be true, and arduino.path and arduino.commandPath should be empty or unset. arduino.useArduinoCli defaults to false while we deprecate support for the Arduino IDE, but there will be a prompt when the extension first activates to switch to the Arduino CLI.

If you want to use a custom version of Arduino CLI, it can be downloaded from the repository's release page. For custom versions, arduino.path must be set to the directory containing the Arduino CLI executable.

Legacy Arduino IDE

Use of the legacy Arduino IDE is not recommended, and support for the legacy Arduino IDE will be removed in a future version of the extension. The legacy Arduino IDE can be installed from the Arduino download page.

Installation

Open VS Code and press F1 or Ctrl + Shift + P or Cmd + Shift + P to open command palette, select Install Extension and type vscode-arduino.

Or launch VS Code Quick Open (Ctrl + P or Cmd + P ), paste the following command, and press enter.

ext install vscode-arduino

You can also install directly from the Marketplace within Visual Studio Code, searching for Arduino.

Get Started

You can find code samples and tutorials each time that you connect a supported device. Alternatively you can visit our IoT Developer Blog Space or Get Started Tutorials.

Commands

This extension provides several commands in the Command Palette (F1 or Ctrl + Shift + P or Cmd + Shift + P) for working with *.ino files:

Keybindings

Options

Option Description
arduino.useArduinoCli Whether to use the Arduino CLI (true) or the legacy Arduino IDE (false) -- defaults to false. If using true, either leave the arduino.path and arduino.commandPath values unset to use the bundled version of Arduino CLI, or point them at a custom version of Arduino CLI. Note that a future version of the extension will change this default to true and remove support for legacy Arduino IDE.
arduino.path Path to the Arduino installation. You can use a custom version of Arduino by modifying this setting to include the full path. Example: C:\\Program Files\\Arduino for Windows, /Applications for Mac, /home/<username>/Downloads/arduino-1.8.1 for Linux. (Requires a restart after change). The default value is automatically detected from your legacy Arduino IDE installation path. To use the Arduino CLI, use the path that contains the arduino-cli executable (e.g. /usr/local/bin), or leave it unset to use the bundled version of Arduino CLI.
arduino.commandPath Path to an executable (or script) relative to arduino.path. The default value is arduino_debug.exe for Windows, Contents/MacOS/Arduino for Mac and arduino for Linux, You also can use a custom launch script to run Arduino by modifying this setting. (Requires a restart after change) Example: run-arduino.bat for Windows, Contents/MacOS/run-arduino.sh for Mac and bin/run-arduino.sh for Linux. To use the bundled version of Arduino CLI, leave this option unset. To use a custom version of Arduino CLI, use arduino-cli.
arduino.additionalUrls Additional Boards Manager URLs for 3rd party packages as a string array. The default value is empty.
arduino.logLevel CLI output log level. Could be info or verbose. The default value is "info".
arduino.clearOutputOnBuild Clear the output logs before uploading or verifying. Default value is false.
arduino.allowPDEFiletype Allow the VSCode Arduino extension to open .pde files from pre-1.0.0 versions of Arduino. Note that this will break Processing code. Default value is false.
arduino.enableUSBDetection Enable/disable USB detection from the VSCode Arduino extension. The default value is true. When your device is plugged in to your computer, it will pop up a message "Detected board ****, Would you like to switch to this board type". After clicking the Yes button, it will automatically detect which serial port (COM) is connected a USB device. If your device does not support this feature, please provide us with the PID/VID of your device; the code format is defined in misc/usbmapping.json.To learn more about how to list the vid/pid, use the following tools: https://github.com/EmergingTechnologyAdvisors/node-serialport npm install -g serialport serialport-list -f jsonline
arduino.disableTestingOpen Enable/disable automatic sending of a test message to the serial port for checking the open status. The default value is false (a test message will be sent).
arduino.skipHeaderProvider Enable/disable the extension providing completion items for headers. This functionality is included in newer versions of the C++ extension. The default value is false.
arduino.disableIntelliSenseAutoGen When true vscode-arduino will not auto-generate an IntelliSense configuration (i.e. .vscode/c_cpp_properties.json) by analyzing Arduino's compiler output.
arduino.analyzeOnOpen When true, automatically run analysis when the project is opened. Only works when arduino.analyzeOnSettingChange is true.
arduino.analyzeOnSettingChange When true, automatically run analysis when board, configuration, or sketch settings are changed.

The following Visual Studio Code settings are available for the Arduino extension. These can be set in global user preferences Ctrl + , or Cmd + , or workspace settings (.vscode/settings.json). The latter overrides the former.

{
    "arduino.useArduinoCli": true,
    "arduino.logLevel": "info",
    "arduino.allowPDEFiletype": false,
    "arduino.enableUSBDetection": true,
    "arduino.disableTestingOpen": false,
    "arduino.skipHeaderProvider": false,
    "arduino.additionalUrls": [
        "https://raw.githubusercontent.com/VSChina/azureiotdevkit_tools/master/package_azureboard_index.json",
        "http://arduino.esp8266.com/stable/package_esp8266com_index.json"
    ],
}

The following settings are as per sketch settings of the Arduino extension. You can find them in .vscode/arduino.json under the workspace.

{
    "sketch": "example.ino",
    "port": "COM5",
    "board": "adafruit:samd:adafruit_feather_m0",
    "output": "../build",
    "prebuild": "./prebuild.sh",
    "postbuild": "./postbuild.sh",
    "intelliSenseGen": "global"
}

Known limitations/restrictions

Pre- and Post-Build Commands

On Windows the commands run within a cmd-, on Linux and OSX within a bash-instance. Therefore your command can be anything what you can run within those shells. Instead of running a command you can invoke a script. This makes writing more complex pre-/post-build mechanisms much easier and opens up the possibility to run python or other scripting languages. The commands run within the workspace root directory and vscode-arduino sets the following environment variables: VSCA_BUILD_MODE The current build mode, one of Verifying, Uploading, Uploading (programmer) or Analyzing. This allows you to run your script on certain build modes only. VSCA_SKETCH The sketch file relative to your workspace root directory. VSCA_BOARD Your board and configuration, e.g. arduino:avr:nano:cpu=atmega328. VSCA_WORKSPACE_DIR The absolute path of your workspace root directory. VSCA_LOG_LEVEL The current log level. This allows you to control the verbosity of your scripts. VSCA_SERIAL The serial port used for uploading. Not set if you haven't set one in your arduino.json. VSCA_BUILD_DIR The build directory. Not set if you haven't set one in your arduino.json.

For example under Windows the following arduino.json setup

{
    "board": "arduino:avr:nano",
    "sketch": "test.ino",
    "configuration": "cpu=atmega328",
    "prebuild": "IF \"%VSCA_BUILD_MODE%\"==\"Verifying\" (echo VSCA_BUILD_MODE=%VSCA_BUILD_MODE% && echo VSCA_BOARD=%VSCA_BOARD%)"
}

will produce

[Starting] Verifying sketch 'test.ino'
Running pre-build command: "IF "%VSCA_BUILD_MODE%"=="Verifying" (echo VSCA_BUILD_MODE=%VSCA_BUILD_MODE% && echo VSCA_BOARD=%VSCA_BOARD%)"
VSCA_BUILD_MODE=Verifying
VSCA_BOARD=arduino:avr:nano:cpu=atmega328
Loading configuration...
<...>

when verifying.

IntelliSense

vscode-arduino auto-configures IntelliSense by default. vscode-arduino analyzes Arduino's compiler output by running a separate build and generates the corresponding configuration file at .vscode/c_cpp_properties.json. vscode-arduino tries as hard as possible to keep things up to date, e.g. it runs the analysis when switching the board or the sketch.

It doesn't makes sense though to run the analysis repeatedly. Therefore if the workspace reports problems ("squiggles") - for instance after adding new includes from a new library - run the analysis manually:

Manual rebuild: Arduino: Rebuild IntelliSense Configuration, Keybindings: Alt + Cmd + I or Alt + Ctrl + I

When the analysis is invoked manually it ignores any global and project specific disable.

IntelliSense Configurations

vscode-arduino's analysis stores the result as a dedicated IntelliSense-configuration named Arduino. You have to select it from the far right of the status bar when you're in one of your source files as shown here:

74001156-cfce8280-496a-11ea-9b9d-7d30c83765c1

This system allows you to setup and use own IntelliSense configurations in parallel to the automatically generated configurations provided through vscode-arduino. Just add your configuration to c_cpp_properties.json and name it differently from the default configuration (Arduino), e.g. My awesome configuration and select it from the status bar or via the command palette command C/C++: Select a Configuration...

Change Log

See the Change log for details about the changes in each version.

Supported Operating Systems

Currently this extension supports the following operating systems:

Support

You can find the full list of issues on the Issue Tracker. You can submit a bug or feature suggestion, and participate in community driven discussions.

Development

Installation prerequisites:

To run and develop, do the following:

To test, press F5 in VS Code with the "Launch Tests" debug configuration.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information please see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Privacy Statement

The Microsoft Enterprise and Developer Privacy Statement describes the privacy statement of this software.

License

This extension is licensed under the MIT License. Please see the Third Party Notice file for additional copyright notices and terms.

Contact Us

If you would like to help build the best Arduino experience with VS Code, you can reach us directly at gitter chat room.