Using Visual Studio Code with Secure Shell (SSH) on a remote host

Visual Studio Code can be used with the Azure Sphere SDK to build and debug code on a remote host via Secure Shell (SSH). Two scenarios are supported:

• Code on remote machine and device on local machine.

• Both code and device on the remote machine.

A third scenario—code on the local machine and device on the remote machine—is not supported.

Set up the local machine

1. Download and install Visual Studio Code.

2. Install the Azure Sphere SDK for Windows or Linux.

3. Install the Azure Sphere extension by searching for Azure Sphere in the Visual Studio Code extension panel and clicking Install.

   Tip

   There are two Azure Sphere extensions, and installing either of them will install both: Azure Sphere UI for the UI component, and Azure Sphere for the workspace component.

4. Install the Remote-SSH extension by searching for Remote-SSH in the Visual Studio Code extension panel and clicking the Install button.

Set up the remote machine

1. We strongly recommend that you set up your remote machine for key-based authentication.
2. Install the Azure Sphere SDK for Windows or Linux.

Code on the remote machine and device on the local machine

1. Connect the device via USB to the local machine.
2. If there isn't a project yet on the remote machine, you can either clone the samples repository or obtain a single project from the Microsoft Samples Browser.
3. Open Visual Studio Code locally.
4. First time only: Open Visual Studio Code from View > Command Palette > Remote-SSH: Add new SSH host, and enter SSH host information as prompted. (By default, a file named config is written to the .ssh directory in your home directory. This sometimes causes permissions problems if your local machine is Windows. You may want to move the file to another directory and specify the absolute path in File > Preferences > Settings > Extensions > Remote - SSH: Config File.)

Connect to the remote machine

1. Connect to the remote machine by executing the Visual Studio Code command View > Command Palette > Remote-SSH: Connect to host (Shift+Ctrl+P).

2. Install the Azure Sphere extensions to the remote machine by searching for Azure Sphere in the Visual Studio Code extension panel and clicking the Install in SSH: [remote name] button. You may need to restart Visual Studio Code and reconnect to the remote machine after installing.

   Tip

   To check if the extension is installed correctly on the remote machine, clear the search box in the extension panel, and make sure Azure Sphere extensions appear in the SSH: [remote name] - INSTALLED view.

3. Open the project folder or workspace using File > Open Folder or File > Open workspace.

Build, deploy to local device, and debug

1. Press F5 to build and debug the project. If the project has not previously been built, or if files have changed and rebuilding is required, Visual Studio Code will build the project before debugging starts.

2. Wait several seconds for Visual Studio Code to build the application, create an image package, deploy it to the board, and start it in debug mode. You'll see status updates in the Output pane along the way.

   First, CMake determines whether the application needs to be built. If so, focus shifts to the output window, which displays the output from CMake/Build.

   Next, the Output pane shows the result as the image package is deployed to the device. Finally, the Debug Console receives focus and shows debugger output.

Use the Visual Studio Code debugger to set breakpoints, pause, step over, step into, restart, or stop the application.

Code and device on the remote machine

1. Connect the device via USB to the remote machine.
2. If there isn't a project yet on the remote machine, you can either clone the samples repository or obtain a single project from the Microsoft Samples Browser.
3. Open Visual Studio Code locally.
4. First time only: Open Visual Studio Code from View > Command Palette > Remote-SSH: Add new SSH host, and enter SSH host information as prompted. (By default, a file named config is written to the .ssh directory in your home directory. This sometimes causes permissions problems if your local machine is Windows. You may want to move the file to another directory and specify the absolute path in File > Preferences > Settings > Extensions > Remote - SSH: Config File.)

Connect to the remote machine and configure remote settings

1. Connect to the remote machine by executing VS Code command View > Command Palette > Remote-SSH: Connect to host (Shift+Ctrl+P).

2. Add remote settings by executing VS Code command View > Command Palette > Preferences: Open Remote Settings, and add the following field to the JSON object (if it's an empty file, you need to wrap this in {}):

       "remote.extensionKind": {
           "ms-vscode.azure-sphere-tools-ui": [
               "workspace"
           ]
       }
   

   You could add this setting to user/workspace settings instead, depending on the setup of your projects and your team.

3. Install the Azure Sphere extensions to the remote machine by searching for Azure Sphere in the Visual Studio Code extension panel and clicking the Install in SSH: [remote name] button. You may need to restart Visual Studio Code and reconnect to the remote machine after installing.

   Tip

   To check if the extension is installed correctly on the remote machine, clear the search box in the extension panel, and make sure Azure Sphere extensions appear in the SSH: [remote name] - INSTALLED view.

4. Open the project folder or workspace using File > Open Folder or File > Open workspace`.

Build, deploy to remote device, and debug

1. Press F5 to build and debug the project. If the project has not previously been built, or if files have changed and rebuilding is required, Visual Studio Code will build the project before debugging starts.

2. Wait several seconds for Visual Studio Code to build the application, create an image package, deploy it to the board, and start it in debug mode. You'll see status updates in the Output pane along the way.

   First, CMake determines whether the application needs to be built. If so, focus shifts to the output window, which displays the output from CMake/Build.

   Next, the Output pane shows the result as the image package is deployed to the device. Finally, the Debug Console receives focus and shows debugger output.

Use the Visual Studio Code debugger to set breakpoints, pause, step over, step into, restart, or stop the application.

Close the connection

To end a remote debugging session, select File > Close Remote Connection.