Arduino CLI for VSCode

A lightweight VSCode extension for Arduino development based on Arduino CLI, providing a complete Arduino development experience.

📖 中文文档

✨ Features

Project-Based Development

All library dependencies and build output files are stored within the project directory, not scattered across arduino15 or other user directories.

Quick Start Guide

🔧 Core Features

• Build & Upload - One-click compile and upload Arduino projects
• Board Management - Support for Arduino, ESP32, ESP8266, STM32, and more
• Library Management - Search, install, and uninstall Arduino libraries
• IntelliSense - Auto-generate C++ IntelliSense configuration

📦 Sidebar Panels

• Boards & Ports - View connected devices and available ports
• Board Manager - Manage board platforms
• Library Manager - Manage installed libraries

⌨️ Keyboard Shortcuts

Mac users: Use Cmd instead of Ctrl

📥 Installation

Prerequisites

1. Install Arduino CLI

   Download from Arduino CLI official releases and choose the appropriate version for your system.

2. Initialize Arduino CLI

   arduino-cli config init
   arduino-cli core update-index
   

🚀 Quick Start

1. Initialize Project

1. Open a folder as workspace
2. Press Ctrl+Shift+P to open command palette
3. Run Arduino: Initialize Project
4. Enter project name, .ino file will be created automatically

2. Select Board and Port

1. Click the Arduino icon in the sidebar
2. Select board and port in the Boards & Ports panel
3. Or use commands Arduino: Select Board and Arduino: Select Port

3. Build and Upload

• Click the ▶️ button in the top-right corner of the editor, or
• Use shortcuts Ctrl+Alt+B to build, Ctrl+Alt+U to upload

4. Serial Monitor

Use Ctrl+Alt+M or command Arduino: Open Serial Monitor to open the serial monitor.

Features:

• Real-time serial data display
• Send data to device
• Timestamp display
• Data export
• Multiple line ending support (LF, CR, CRLF)

5. 🤖 AI-Assisted Debugging (Copilot Integration)

This extension supports GitHub Copilot Agent directly reading serial monitor data - no manual copy-paste needed!

How to use:

1. After initializing an Arduino project, .github/copilot-instructions.md is automatically created
2. Open the serial monitor, data is automatically saved to .vscode/serial-data.log
3. Ask questions about serial data directly in Copilot Chat

Example conversations:

• "Help me check what's wrong with the serial output"
• "Analyze the data sent by the device"
• "What errors are shown in the serial monitor"
• "Check if the Arduino output is normal"

Copilot will automatically read and analyze serial data, greatly improving debugging efficiency!

⚙️ Configuration

Search arduino in VS Code settings to view all configuration options.

Basic Configuration

Build Configuration

Serial Configuration

Advanced Configuration

Chinese Path Compatibility (Windows)

⚠️ About Chinese Paths: Some toolchains (like arm-none-eabi-gcc) cannot handle Unicode paths correctly, causing build failures. When these options are enabled, the extension automatically redirects build output to a temp directory (Chinese converted to Pinyin) and copies artifacts back after build. { "arduino.boardManager.additionalUrls": [ "https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json", "https://arduino.esp8266.com/stable/package_esp8266com_index.json" ] }

**Common URLs:**
- **ESP32**: `https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json`
- **ESP8266**: `https://arduino.esp8266.com/stable/package_esp8266com_index.json`
- **STM32**: `https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json`

---

## 📋 Command List

Press `Ctrl+Shift+P` to open command palette, type `Arduino` to see all commands:

### Project Management
| Command | Description |
|---------|-------------|
| `Arduino: Initialize Project` | Initialize Arduino project |
| `Arduino: Generate IntelliSense Config` | Generate IntelliSense configuration |

### Build & Upload
| Command | Description |
|---------|-------------|
| `Arduino: Build` | Build project |
| `Arduino: Upload` | Upload to board |
| `Arduino: Export Compiled Binary` | Export compiled binary files |
| `Arduino: Clean Build` | Clean build cache |
| `Arduino: Open Build Folder` | Open build output directory |

### Board Management
| Command | Description |
|---------|-------------|
| `Arduino: Select Board` | Select target board |
| `Arduino: Select Port` | Select serial port |
| `Arduino: Configure Board Options` | Configure board options |
| `Arduino: Refresh Boards` | Refresh board list |
| `Arduino: Install Board Platform` | Install board platform |
| `Arduino: Manage Installed Platforms` | Manage installed platforms |
| `Arduino: Add Board Manager URL` | Add third-party board URL |
| `Arduino: Update Board Index` | Update board index |

### Library Management
| Command | Description |
|---------|-------------|
| `Arduino: Search Library` | Search libraries |
| `Arduino: Install Library` | Install library |
| `Arduino: Uninstall Library` | Uninstall library |
| `Arduino: Add .ZIP Library...` | Import library from ZIP file (supports GitHub downloads) |
| `Arduino: Install Missing Libraries` | Install missing libraries |
| `Arduino: Update Library Index` | Update library index |

### Serial Monitor
| Command | Description |
|---------|-------------|
| `Arduino: Open Serial Monitor` | Open serial monitor |
| `Arduino: Close Serial Monitor` | Close serial monitor |
| `Arduino: Change Baud Rate` | Change baud rate |
| `Arduino: Switch Serial Monitor Mode` | Switch monitor mode |

### CLI Configuration
| Command | Description |
|---------|-------------|
| `Arduino: Configure CLI Path` | Configure CLI path |
| `Arduino: Auto Detect CLI` | Auto-detect CLI |
| `Arduino: Show CLI Version` | Show CLI version |

---

## 📁 Project Structure

When using this extension, your project will have the following structure:

my-project/ ├── my-project.ino # Arduino main program ├── .arduino/ │ ├── config.json # Project configuration (board, port, etc.) │ └── build/ # Build output directory ├── .github/ │ └── copilot-instructions.md # Copilot AI instructions (auto-generated) └── .vscode/ ├── c_cpp_properties.json # IntelliSense configuration (auto-generated) └── serial-data.log # Serial data log (generated at runtime)

### Project Configuration File

`.arduino/config.json` stores board and port configuration:

```json
{
  "board": "esp32:esp32:esp32",
  "port": "COM3",
  "boardOptions": {
    "FlashFreq": "80",
    "UploadSpeed": "921600"
  }
}

🔧 Troubleshooting

⚠️ Windows Path Length Limitation (Important)

On Windows, when the project path is long, you may encounter the following compilation error:

fatal error: bits/os_defines.h: No such file or directory

Root Cause:

• Windows has a default 260-character path length limit
• Some toolchains (like STM32's xpack-arm-none-eabi-gcc) have deep internal directory structures
• When the project's .arduino-cli/data directory path is too long, the GCC compiler cannot correctly resolve header files

Solutions:

Option 1: Enable Windows Long Path Support (Recommended)

1. Press Win+R, type regedit to open Registry Editor
2. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
3. Find LongPathsEnabled, double-click and change the value to 1
4. Restart your computer for changes to take effect

Or use PowerShell (run as Administrator):

Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1

Option 2: Use Shorter Project Paths

Place your project in a shorter path, for example:

• ✅ C:\Arduino\myproject
• ❌ C:\Users\username\Desktop\my-long-folder-name\arduino-projects\myproject

Option 3: Modify arduino-cli Data Directory

Edit .arduino-cli/arduino-cli.yaml in your project, point data directory to a shorter path:

directories:
    data: C:/ArduinoData
    downloads: C:/ArduinoData/downloads
    user: ./user  # Keep user libraries in project directory

💡 Note: This issue mainly affects platforms using deep directory structure toolchains (like STM32). ESP32, ESP8266, and similar platforms are usually not affected.

CLI Not Found

Arduino CLI not configured or path invalid

Solution:

1. Run Arduino: Auto Detect CLI for auto-detection
2. Or run Arduino: Configure CLI Path to configure manually

Board Not Recognized

Solution:

1. Run Arduino: Update Board Index to update index
2. Ensure third-party board URLs are added
3. Run Arduino: Install Board Platform to install the platform

Build Failed

Solution:

1. Check if the correct board is selected
2. Run Arduino: Install Missing Libraries to install missing libraries
3. Check output panel for detailed error messages

Upload Failed

Solution:

1. Ensure correct port is selected
2. Close other programs using the serial port (including serial monitor)
3. Check USB connection and drivers

📄 License

MIT License - See LICENSE file for details