VSCODE Devcontainer for Arduino

This is a self-contained environment that allows compiling and uploading Arduino source code without having to install anything on your computer, beside VSCode and Docker. It uses the VSCode's devcontainer built-in feature.

Licensing

The included Docker file, the devcontainer.json file and the hello-world sample are licensed under the MIT License. All other files are governed by their respective licenses.

How it works

This devcontainer is based on Microsoft's CPP devcontainer using Debian and contains the required extensions to facilitate Arduino development.
The devcontainer is configured to launch the container with --privileged options. This is required to access the serial ports from inside the Docker container. If your feel unsafe about that, you can remove this option and add an UDEV rule to configure the file permissions on the Arduino device automatically.

Environment

This devcontainer has been tested with the following environment:

• Ubuntu 22.04 running on WSL 2.2.4.0 (on Win11 23H2)
• Docker 27.1.1
• VSCode 1.92.0

How to use the devcontainer

1. Open the project in VSCode: File->Open Folder
2. Reopen it in devcontainer:
   1. CTRL+SHIFT+P to open the command pallet
   2. Remote-Containers: Reopen in container

Inside the devcontainer

Most of the option below are also available from the status bar

Selecting the Board

From the command pallet, type Arduino: Board config

Opening the serial monitor

From the command pallet, type Arduino: Open serial monitor

Opening the library manager

From the command pallet, type Arduino: Library manager

Working with the code

ALT-CTRL-R: Compile only
ALT-CTRL-U: Compile and upload to the Arduino device

For more information about the Arduino extension for VSCode, consult this page.

External librairies

If you need to install external librairies, use the arduino-cli lib install command. See the end of the Docker files for more information.

Select your board for the project

This devcontainer setup uses the Arduino CLI 1.x onwards. Which means the installation of the legacy Arduino IDE 1.x is no longer necessary. Checkout the vscode.vscode-arduino extension for further reads on this topic.

The Arduino CLI is used to install the necessary platform packages of the boards, so that manual installation of these packages via the Arduino Board Manager is no longer necessary after the container has been started.

The parameters PACKAGE_URL and PLATFORM in devcontainer.json can be set accordingly. For example for a project with the ESP8266 board:

   "build": {
		"dockerfile": "Dockerfile",
		"context": ".",
		"args": {
			// ... other parameters ...
			// Project specific settings
			"PACKAGE_URL": "http://arduino.esp8266.com/stable/package_esp8266com_index.json",
			"PLATFORM": "esp8266:esp8266" 
		}

Hint: Look up the URL in this collection on GitHub on 3rd party board support for the PACKAGE_URL parameter.

Don't forget to configure the corresponding board type in the .vscode/arduino.json file. Using the ESP8266 NodeMCUv2 as an example, it looks like this:

   {
    "board": "esp8266:esp8266:nodemcuv2",
   }

Hint: Use the arduino-cli board listall command to use all available options.

Using the Arduino CLI

• Check Arduino CLI Reference on how to use arduino-cli <command> [flags...]
  • Also check this article to have an example with an ESP8266 as a reference on how to use these commands

Troubleshooting

Pre-requisites on Windows Subsystem for Linux (WSL2)

Check out the Microsoft Documentation on how to connect USB devices and perform the installation steps for USBIPD-WIN.

After every restart of WSL perform the following steps (little bit anoying...):

1. Open your WSL VM with wsl in a PowerShell window and keep the WSL running.
2. List all USB devices connected to Windows by opening a new PowerShell window in administrator mode.

   usbipd list

   Make sure the USB device is shared. Otherwise use (admin priviledges needed):

   usbipd bind --busid <busid_e.g:_4-4>

3. Attach the USB device to WSL (no admin priviledges needed)

   usbipd attach --wsl --busid <busid_e.g:_4-4>

4. Perform the following steps in your running WSL shell. List the attached USB devices by running:

   lsusb

   You shoud see the device you just attached and be able to interact with it using normal Linux tools.

Find the device path on your Linux machine and make it accessible from within your devcontainer

In Linux serial ports are /dev/tty* (where "*" can be a number e.g. 0-3 or something like USB0) not COMn which is the notation used in Windows.

1. Check where your device is attached to:

   dmseg | grep tty

   ... which outputs something like: usb 1-1: ch3411-uart convertor now attached to ttyUSB0. This means your device path is /dev/ttyUSB0

2. Create a mount point in the devcontainer.json file to have access to this device within your devcontainer.

   "mounts": [
    	"source=/dev/ttyUSB0,target=/dev/ttyUSB0,type=bind"
   ],

   For this option the devcontainer needs to run in priviledged mode. Add the following to the configuration:

   "runArgs": [
    	"--privileged",
    	"--cap-add=SYS_PTRACE",
    	"--security-opt",
    	"seccomp=unconfined"
    ],

   For further information consult the Docker documentation for options (runArgs) of the docker container run command.

   Note: This may be not the best option in regards of security. I use it in my home lab environment for developing. BUT there are other possibilities (cgroup method). Checkout this discussion on stackoverflow.

3. For your Arduino VS Code extension you can now configure the serial port (e.g. /dev/ttyUSB0) in the .vscode/arduino.json file as follows:

   {
      "port": "/dev/ttyUSB0",
   }

Add additional Boards Manager URLs to use e.g. an ESP8266

1. In the devcontainer.json file configure the additional URL in settings (here for the ESP8266):

   "settings": { 
    	"arduino.additionalUrls": [
    		"http://arduino.esp8266.com/stable/package_esp8266com_index.json"
    	]
    },

2. In VS Code use the >Arduino: Board Manager command, search for e.g. ESP8266 and install the packages
3. Use the >Arduino: Board Config command to configure the board
4. Optional: Another option is to configure the settings in the .vscode/ardunio.json file as follows:

   {
    "board": "esp8266:esp8266:nodemcuv2",
    "configuration": "xtal=80,vt=flash,exception=disabled,stacksmash=disabled,ssl=all,mmu=3232,non32xfer=fast,eesz=4M2M,led=2,ip=lm2f,dbg=Disabled,lvl=None____,wipe=none,baud=115200"
   }

Further resources

• Checkout this article for more information on how to set up the WSL
• Udev is the Linux subsystem that supplies your computer with device events... get amiliar with it. Check out this article.
  • Use sudo udevadm monitor -u to monitor udev events
  • Check also the Arduino Documentation on how to create a udev rule to enable the Arduino IDE to access the serial port and upload code
• Checkout this article for the general steps in the Arduino IDE to configure a ESP-12E / ESP-12F / NodeMCU.
  • Configure the Board Manager URL
  • Flash boards