Skip to content

Latest commit

 

History

History
273 lines (168 loc) · 13 KB

using-docker-container.md

File metadata and controls

273 lines (168 loc) · 13 KB
Raw

Using Docker Container

The Espressif docker image has been released here, but for idf.py flash and idf.py monitor to work in the container the serial ports should be configured to be passed to WSL from host Windows machine.

In this tutorial will show you how to develop your projects based on Visual Studio Code + ESP-IDF extension + ESP-IDF Docker Image to execute all ESP-IDF extension features.

Required tools

you need to install the following tools before starting our projects:

  1. Ubuntu 20.04 on Windows
  2. Visual Studio Code
  3. usbipd-win
  4. Docker Desktop For Windows

Other tools are defined in Dockefile and will be part of the executed container.

Docker Desktop

Docker Desktop is an application for MacOS and Windows machines for the building and sharing of containerized applications. For more details, the user can refer to here, but the role of docker here is to import the ESP-IDF Docker Image and manage it, such as start,restart,close etc.

NOTE: the default installing path of docker is C disk, so please move to other disks with mklink commands if the space size of C disk is not enough.

Ubuntu 20.04 on Windows

WSL is present starting from Windows 10 OS, so we can check the WSL list with the powershell command prompt, as below

wsl -l -o

so to install WSL on windows, please type in the following command:

wsl --install --distribution　Ubuntu-20.04

where Ubuntu-20.04 is for your information.

usbipd-win

To access the USB,serial,JTAG devices which are from the local windows, this tools must be installed, else it is impossible to download,monitor and debug on IDF docker image side. the way to install it, it is also same as windows applications, so it will not be described in detail here.

configuration

we still need to do a bit configurations after installing the four tools above:

Ubuntu 20.04 on Windows

the default version of WSL is 1 after installing, it needs to upgrade to version2 and then set it as the default distribution with the following steps:

  1. check the current WSL version

    wsl -l -v

  2. please upgrade to version 2, if not

    wsl --set-version Ubuntu-20.04 2

  3. set the distribution, as below:

    wsl -s Ubuntu 20.04

at last, to check if the commands have taken effect with wsl --status command.

Docker Desktop For Windows

As the distribution Ubuntu 20.04 has been updated to version 2, so it needs to modify accordingly from docker side and choose the Ubuntu 20.04 as the default WSL integration as well.

usbipd

From windows side this tool should be already configured. However usbipd still need to be installed on the WSL, that is, open the WSL from Windows menu and then type in the following the commands separately:

apt install linux-tools-5.4.0-77-generic hwdata
update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/5.4.0-77-generic/usbip 20

If any errors are found, try updating apt-get packages first.

apt-get update

NOTE: IF you are using a container made with the Dockerfile from this extension .devcontainer generated directory (when you create a project using the ESP-IDF: New Project, ESP-IDF: Add docker container configuration or ESP-IDF: Show Examples commands).

with this the local Windows and WSL are all installed. To check usbipd tool is working well on both side, please follow the following steps:

  1. open PowerShell command prompt with administrator right and then type in the command usbipd wsl list:

    as you can see, all USB devices from Windows have been found and not attached sate.

  2. to access the specified device from local Windows on WSL, it needs to bind this device. Open PowerShell command prompt with administrator rights and then type in the command usbipd bind -b <BUSID>:

    Note: this command needs to be used only one time,unless the computer has restarted. 1-1 is the device's bus id I would like to bind.

  3. after binding, please attach the specified device to WSL with usbipd wsl attach --busid 1-1 command in the powershell command prompt.

  1. At last, let us check if it works well on both side and type in dmesg | tail command on WSL side.

    as we can see above, 1-1 device has been attached to ttyACM0, that means WSL can access the 1-1 USB device now.

Visual Studio Code

To connect to the ESIDF docker image, install the Remote - Containers、Remote Development and ESP-IDF extensions, as below:

Practice

After all previous steps have taken effect, the WSL or docker container should be ready to use. Here is an example to show you how to utilize these tools.

example project with docker container

Using blink and hello_world projects as examples, If you have more example projects, you can put them in the same folder and mount them together in the IDF Docker image; otherwise, it will take your much more space size on your disk as you need to create one container for each example project, that is not a good solution.

as seen from snapshot above, blink and hello_world example projects have been put in the same folder and we only need to open this folder with vscode:

some readers may see that there is a .devcontainer folder in the example_project folder, which is not included by default; this is generated by using the ESP-IDF extension of Visual Studio Code to create and configure the IDF docker image for container development.

If the user readers also need to generate their own .devcontainer folder content, as follows:

  1. open example project with vscode and then press F1
  2. In the pop-up dialog box, search for the ESP-IDF: Add docker container configuration command
  3. .devcontainerfolder will be generated for the currently opened project.

For more information about devcontainer.json, please refer to the comments.

// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
// https://github.com/microsoft/vscode-dev-containers/tree/v0.183.0/containers/ubuntu
{
  /* A name for the dev container displayed in the UI */
  "name": "ESP-IDF",
  /* container name when creating container */
  "image": "espressif/idf:latest",
  /* mount the local folder to /workspaces folder of docker image */
  "workspaceMount": "source=${localWorkspaceFolder},target=/workspaces,type=bind",
  /* the path of workspace folder, that means this folder will be opened after container is running
   */
  "workspaceFolder": "/workspaces/blink",
  /* mount the vscode extensions to the target path, and then they don't need to install again when rebuilding the container
   */
  "mounts": [
    "source=extensionCache,target=/root/.vscode-server/extensions,type=volume"
  ],
  /* follow the commands of Dockerfile to create the container
   */
  "build": {
    "dockerfile": "Dockerfile"
  },
  /* Machine specific settings that should be copied into the container
   */
  "settings": {
    "terminal.integrated.defaultProfile.linux": "bash",
    "idf.espIdfPath": "/opt/esp/idf",
    "idf.customExtraPaths": "",
    "idf.pythonBinPath": "/opt/esp/python_env/idf5.0_py3.8_env/bin/python",
    "idf.toolsPath": "/opt/esp",
    "idf.gitPath": "/usr/bin/git"
  },
  /* An array of extensions that should be installed into the container. */
  "extensions": ["ms-vscode.cpptools", "espressif.esp-idf-extension"],
  /* start the container with privileged mode, else the devices cannot be accessed on the docker image.
   */
  "runArgs": ["--privileged"]
}

At this point, all related configurations have been completed.

Create a container

Create a container and then start your development by clicking the >< green button at the bottom left of Visual Studio Code and select Open Folder in Container to start creating a container (It will be slightly slower, because to download the Docker image of ESP-IDF, you only need to download it once), and finally open the Blink example project; if you need to switch to another project, just change it from "workspaceFolder": "/workspaces/blink" to "workspaceFolder": "/workspaces/The name of the sample project you want to open", and then re-selectOpen Folder in Container, as follows:

at this moment, you can start to use the Blink example project for building, flashing, monitoring, debugging, etc.

Building the project

Here taking the esp32-c3 as an example, users only need to change the target device from esp32 to esp32-c3, as below:

next, start to build the example project, as below:

Flashing to your device

after building, we can use the following ways to download the firmware.

External USB-Serial

Based on the description above, users can follow the instructions usbipd section mentioned. here Silicon Labs CP210x USB to UART Bridge is taken as an example, it has been attached to docker image:

as you can see, this device has attached to ttyUSB0, so idf.port also need to change accordingly.

but, the container doesn't know the configuration has changed yet at this moment.

so users need to reopen the container, that is Reopen Folder Locally and then the new configuration wil be reloaded as well.

at last, click the flash button and start to download the firmware.

Internal USB-serial

Just as the external usb-serial, the only difference is the number attached. where the external usb-serial is ttyUSBx, while the internal usb-serial is ttyACMx.

USB-JTAG

Same as External USB-Serial and Internal USB-serial, but it needs to configure the following extra parameters:

the interface is the same as Internal USB-serial, that is ttyACMx:

debugging

After following USB-JTAG, press F5 to start to debug:

Precautions

  1. When the container is created for the first time, it will prompt that the ESP-IDF extension cannot be activated because it depends on the Microsoft C++ tools extension. You only need to reopen the container again. This is because the ESP-IDF extension is dependent on the C++ Tools extension being installed first.
  2. If you want to debug on Windows, you need to unplug the USB cable and re-plug in it again, otherwise the corresponding USB port cannot be found in the Windows device manager.
  3. Docker Desktop For Windows needs to be opened and cannot be closed during container development.