Skip to content

Latest commit

 

History

History
90 lines (65 loc) · 7.4 KB

README.md

File metadata and controls

90 lines (65 loc) · 7.4 KB

vscode-arduino-api

Arduino API for Arduino IDE 2.x external tools developers using VS Code extensions.

This VS Code extension does not provide any functionality but a bridge between the Arduino IDE 2.x and external tools implemented as a VS Code extension. Please reference arduino/arduino-ide#58 to explain why this VSIX has been created. This extension has nothing to do with the Visual Studio Code extension for Arduino. This extension does not work in VS Code.

API

Exposes the Arduino context for VS Code extensions:

Name Description Type Note
sketchPath Absolute filesystem path of the sketch folder. string
compileSummary The summary of the latest sketch compilation. When the sketchPath is available, but the sketch has not been verified (compiled), the buildPath can be undefined. CompileSummary ⚠️ @alpha
fqbn The Fully Qualified Board Name (FQBN) of the currently selected board in the Arduino IDE. string
boardDetails Lightweight representation of the board's detail. This information is provided by the Arduino CLI for the currently selected board. It can be undefined if the fqbn is defined, but the platform is not installed. BoardDetails ⚠️ @alpha
port The currently selected port in the Arduino IDE. Port
userDirPath Filesystem path to the directories.user location. This is the sketchbook path. string ⚠️ @alpha
dataDirPath Filesystem path to the directories.data location string ⚠️ @alpha

How to Use

If you're developing an external tool for the Arduino IDE, this extension will be available at runtime from the IDE.

If you want to use the Arduino APIs, you have to do the followings:

  1. Install the Arduino API types from npm:

    npm install vscode-arduino-api --save

  2. Consume the ArduinoContext extension API in your VS Code extension:

    import * as vscode from 'vscode';
import type { ArduinoContext } from 'vscode-arduino-api';

export function activate(context: vscode.ExtensionContext) {
  const arduinoContext: ArduinoContext = vscode.extensions.getExtension(
    'dankeboy36.vscode-arduino-api'
  )?.exports;
  if (!arduinoContext) {
    // Failed to load the Arduino API.
    return;
  }

  // Use the Arduino API in your VS Code extension.

  // Read the state.
  // Register a command to access the sketch path and show it as an information message.
  context.subscriptions.push(
    vscode.commands.registerCommand('myExtension.showSketchPath', () => {
      vscode.window.showInformationMessage(
        `Sketch path: ${arduinoContext.sketchPath}`
      );
    })
  );

  // Listen on state change.
  // Register a listener to show the FQBN of the currently selected board as an information message.
  context.subscriptions.push(
    arduinoContext.onDidChange('fqbn')((fqbn) =>
      vscode.window.showInformationMessage(`FQBN: ${fqbn}`)
    )
  );
}

FAQs

  • Q: What does @alpha mean?
  • A: This API is in an alpha state and might change. The initial idea of this project was to establish a bare minimum layer and help Arduino IDE 2.x tool developers start with something. I make breaking changes only when necessary, keep it backward compatible, or provide a migration guide in the future. Please prepare for breaking changes.
  • Q: Why do I have to install vscode-arduino-api from npm.
  • A: vscode-arduino-api only contains types for the API. The actual code will be part of the VS Code extension.
  • Q: I cannot find the dankeboy36.vscode-arduino-api extension in neither the VS Code Marketplace nor Open VSX Registry.
  • A: Correct. This solution targets the Arduino IDE 2.x. The IDE will contain this VSIX at runtime and will activate it before your tool VSIX. You do not even have to add dankeboy36.vscode-arduino-api to the extensionDependencies. I might publish the VSIX later when it works in VS Code. By the way, the VSIX is signed by a verified publisher. You can get the latest version from the GitHub release page.
  • Q: Are there plans to support it in VS Code?
  • A: Sure.