Search by Tags

Python Development and Debugging on Torizon Using Visual Studio Code

 
Applicable for

Article updated at 13 Jun 2019
Subscribe for this article updates

Introduction

Those instructions have been tested on Linux (Ubuntu 18.04) and Windows 10.

On Windows 10 you need to perform some extra configuration steps to allow the required tools to work, those Windows-specific steps will be described in the instructions when required.

If you are not familiar about the conventions we use in the documentation, please check our online reference.

GitHub Repository

You will find back-up material for this article, as well as additional samples and other resources in the python-container repository on Toradex GitHub.

Prerequisites

You need to install the following applications on your development machine:

Windows 10

On Windows you also have to enable the Windows Subsystem for Linux, you can follow instructions provided by Microsoft.

Configure the Target Device

On the target device you should just install a Torizon image with Docker support. Your device must be connected to the local network.

Since many commands are executing over SSH, it may be a good idea to enable passwordless SSH connection to the target, so you don't have to input a password at every connection. Remember that the default password for the torizon user is "torizon".

Create a New Python Project

To start a new Python project you can simply copy the contents of the /template folder inside the source repository, this will provide all the scripts and configuration files you will need to run and debug your Python code on torizon. The folder contains some files you will need to edit to integrate your application with Torizon.

requirements.txt

This file is typically used to list additional packages required to run your Python application. Those packages will be installed using the pip package manager. List all dependency of your application inside this file and those will be automatically installed inside the container that will be used to run it. The containers will be rebuilt automatically every time you change this file. You can just list the packages you need, one per line. Optionally you can specify a version for the packages.

requirements.txt
numpy
geoip2
 

setup.sh and cleanup.sh

Sometimes packages require some additional components to be present in your system. With setup.sh you can add installation commands required to add those packages to the running container (the template containers we provide use debian-buster as base, so you can just use apt-get package manager to perform those operations). You may also download packages in source code or other formats and add additional data files your application may need. Some components may be needed only during the installation. For example some Python packages build C code during installation, so they will need C compiler in that phase (likely the build-essential package in debian), but not when running. If there are some packages you can remove to reduce size of the resulting container you can use cleanup.sh for this purpose. Our samples provide setup and cleanup scripts with relatively complex operations, so you can get an idea of how to implement those scripts for your specific application requirements.

This is a sample setup script that installs curl (not part of the slim debian-buster image) to download some data files required by a package used by the application.

setup.sh
#!/usr/bin/env sh
 
# this is a simple script that could be used to add additional features to the container used to run your Python software
if [ "$1" = "release" ]
then
    echo "This is a release build"
elif [ "$1" = "debug" ]
then
    echo "This is a debug build"
else
    return 1
fi
 
 
# if you need to install additional package is a good idea to limit dependecies and clean up the cache afterwards (in cleanup.sh)
apt-get update
apt-get install -y --no-install-recommends curl
 
# download geolite database (we use insecure to minimize components installed in the container for this purpose), unzip it and remove the downloaded file
curl -L --insecure https://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz --output /GeoLite2-City.tar.gz
tar --strip 1 -xvzf /GeoLite2-City.tar.gz
rm /GeoLite2-City.tar.gz
 

Since curl is not needed to run the application, the matching cleanup script will remove it from the system:

cleanup.sh
#!/usr/bin/env sh
 
# this is a simple script that could be used to cleanup after you installed additional features via pip
if [ "$1" = "release" ]
then
    echo "This is a release build"
elif [ "$1" = "debug" ]
then
    echo "This is a debug build"
else
    return 1
fi
 
 
# remove packages you will not need to run your application and clean cache
apt-get -y remove curl
apt -y autoremove
rm -rf /var/lib/apt/lists/*
 

Configure Visual Studio Code

Open the project folder using Visual Studio code and you are going to be ready to configure it to debug and deploy your application.

You should be able to browse the contents of your folder. Open the file named settings.json in the .vscode folder and change configuration parameters according to your application and device settings:

.vscode/settings.json
{
    "toradexpython.targetDebugPort": "6502",
    "toradexpython.targetDevice": "192.168.1.128",
    "toradexpython.containersTemplatePath": "../containers",
    "toradexpython.mainscript": "hello.py",
    "toradexpython.containerParms": "",
    "toradexpython.containerParms_debug": "",
    "toradexpython.containerParms_release": "",
    "toradexpython.containerTemplate_debug": "python3/python-runtime-dbg",
    "toradexpython.containerTemplate_release": "python3/python-runtime"
}
 

You will have to configure the right IP/hostname for the device you plan to use to debug your application, the name of the Python file containing your entry point and the path of the container templates used to run your application (it's a good idea to use relative paths). Depending on the template you choose you can use python2 or python3 runtime. In the sample above we are referencing python3, you replace that with python2 to use that runtime.

Debug your application

You can just place breakpoint in the locations where you need to inspect code execution and then just press F5 to start debugging. The first time you do that the integration scripts will build the debug container, this may take some times, depending on the packages you need to install. Once the container has been built it will be also automatically deployed and started on the target. Container will be rebuilt and re-deployed also if you changed requirements.txt or the setup scripts (setup.sh and cleanup.sh). If you just edit and change your own Python code those steps will be skipped and the debugger will be ready just a few seconds after you start it.

Package and Deploy Your Application

When you are happy about your application and want to run it directly on a Torizon device you will have to build a release container that will include the Python runtime, your application and all its dependencies. To do this:

  • press ctrl+P to open command palette
  • type task buildreleasecontainer to start build.
  • build of the release container image will start.
  • build should complete successfully

    Successfully built XXXXXXXXX
    Successfully tagged YYYYYYYYY:latest
    
  • The new image tag will be the name of your application folder, you will be able to change that by running docker build with a different tag (see chapter "customizing containers").

  • press ctrl+P again to re-open the command palette.
  • type task runreleasecontainer to deploy and run your container on the device.

Customize Containers

Python applications will not run directly on Torizon, they will be hosted inside a container.

Toradex provides base containers for Python 2.x and 3.x applications, those need some customization to provide debugging capabilities and to host your application directly inside the container for release builds.

Inside this repo you will find a folder named "containers", inside the folder you will find two subfolders, named python2 and python3, they contains the same subfolders:

  • python-runtime: This container will provide the Python runtime, pip (package manager) and setup-tools (required to install most of the packages supported by pip). It will also add contents of your project folder to the /app folder inside the container and automatically run your main script when the container is started.

  • python-runtime-dbg: This container also provides the pyhton runtime, pip and setup-tools. In addition to that it provides the Python debugger for Visual Studio (ptvsd) and runs it when container is started, waiting for a connection from the development machine.

Those containers can be customized by changing their Dockerfile or by creating a new Dockerfile that uses them in their "FROM" statement.

The container name should match the folder name, and custom names may be configured in settings.json for your specific project.

You can add additional exposed port using the EXPOSE clause (this is needed for server ports, not for ports your application accesses as a client) or add additional os components needed by your application.

Base containers are based on debian buster, so you can add components invoking the apt package manager.

If you just need to specify different parameters at runtime (mapping ports or folders, sharing devices, running container in privileged mode or with a different user account) you can do that using toradexpython.containerParms or toradexpython.containerParms.debug/release if those parameters are required only for a specific configuration.