IoT Catalyst DevOps - User Guide

Table Of Contents

• Introduction
• Quick Start
• Prerequisites
  • Compatibility
• Examples
• General Concepts
  • Hypervisor Path
  • Container Workspace
  • IoT Catalyst Studio Credentials
• Extension Settings
  • Auto Sync
  • Hypervisor Folder
• IDE Features
  • Digital Thing Features (Code Manager)
    • Adding a New Feature
    • Adding Function/Action Parameters
    • Removing a Feature
    • Removing Function/Action Parameters
  • Extension Output
• Commands
  • Connect to a Remote Host
  • Select Hypervisor Folder
  • Select Container Folder
  • Create a new Digital Thing
  • Mount a new Container
  • Install Python Dependency
  • Compile Digital Thing Code
  • Upload Digital Thing to IoT Catalyst Library
  • Deploy Changes to IoT Catalyst Library
  • Debug Container
  • Open Local Container Details in IoT Catalyst Studio
• Known Issues
  • Container fails to be unmounted if opened in VSCode
  • Terminal Default Profile in Windows Environment
  • SSH Remote: Troubles while connecting
  • SSH Remote: VSCode Terminal not loading .profile
  • Incompatible with WSL
  • Missing support for type hints

Introduction

IoT Catalyst DevOps Extension (just DevOps from now on) is the official VS Code extension released by the IoT Catalyst DevOps team.
It makes fast and easy the process of programming IoT Catalyst Containers, supporting the programmer during the phase of design, test and debug.

By using DevOps, users can achieve a really fast development loop without needing to leave VS Code.

Here's a typical usage scenario:

1. Create a new Digital Thing and instantiate it on a new Container
2. Design the Digital Thing through the "IoT Catalyst DevOps" Panel
3. Debug the updated Digital Thing Code to ensure its correctness
4. Deploy the updated Digital Thing to the IoT Catalyst library

NOTE: Please take a look at Known Issues.

Quick Start

We strongly recommend taking a look at our examples.

Prerequisites

• VSCode Microsoft's Python Extension v2023.6.1
• A valid IoT Catalyst license and developer account
• An IoT Catalyst Hypervisor installed on your development machine

Compatibility

The compatibility table between DevOps and the IoT Catalyst Hypervisor SDK is reported below.

IoT Catalyst DevOps Version	IoT Catalyst Hypervisor SDK Version
1.0.1	<= 1.6.1.012
>= 2.0.0	>= 1.6.2

Examples

The complete list of DevOps walkthroughs and examples is available here.

General Concepts

Here are mentioned some concepts many commands rely on.

Hypervisor Path

Some commands require additional knowledge about the entities they are working with (for instance, the IoT Catalyst Studio URL). This knowledge is, when possible, extracted from the Hypervisor installed on the development machine. Therefore DevOps prompts the user for the Hypervisor installation path (refer to this command for more details).

Container Workspace

Commands which act on an IoT Catalyst Container or a Digital Thing require to be executed in a workspace that includes the Container folder. That's why, when executing a command X while not being in a Container Workspace, you may encounter the following warning message:

To fix this, just launch the Select Container Folder command and then launch X again.

IoT Catalyst Studio Credentials

Some commands which need to call the IoT Catalyst Studio API may prompt the user for a valid pair of IoT Catalyst username and password:

Extension Settings

DevOps is customizable through Visual Studio Code Settings.

Go to "File" > "Preferences" > "Settings", and then to the "Extensions" > "IoT Catalyst DevOps" section.

Here are described the available settings.

Auto Sync

When developing a Digital Thing using the Code Manager provided by DevOps, you will notice a popup appearing every time you save changes to the Digital Thing artifacts (ie. the code or the Bill of Features):

This is because, if you make manual changes, DevOps tries to keep the Bill of Features in sync with the Code and vice versa.

Please do not be afraid of this alert, since it's just here to notify that someone else is taking care to keep all in sync for you!

If you want to get rid of this alert, you can disable the warning message by setting the "Auto Sync" configuration to either On or Off.

Hypervisor Folder

You can use this setting to tell DevOps which IoT Catalyst Hypervisor must be used while the extension is active.

IDE Features

DevOps ships with a series of simplified GUIs which allow to design and debug a Digital Thing in a matter of clicks.

Once you install the Extension, a new panel becomes available in the VSCode editor: the "IoT Catalyst DevOps" panel.

Digital Thing Features (Code Manager)

Automatic code generation for Digital Things (Python + XML Bill of Features)

This graphical interface is activated when a IoT Catalyst Container is present inside the VSCode workspace.

When active, it shows all the features defined in the Bill of Features of the Digital Thing instantiated by the Container. For example, the following image depicts a Digital Thing having a Data feature called "dato1" and an Event feature called "event1".

You can leverage the contextual buttons to model the shape of your Digital Thing. Here are described typical operations.

Adding a New Feature

Define a new feature and automatically generate the Python boilerplate code along with a new entry in the .bof file.

To a add a new feature, use the "Add Feature" button located to the right of the view title. You will be prompted for some information about the new feature. Here's an example of the workflow:

Adding Function/Action Parameters

Update a Function or Action feature definition by adding a parameter to it.

When you have a feature of type "Function" or "Custom Action", you can add a maximum of 5 parameters to it via DevOps.

Just locate the feature inside the treeview: here, locate its child node named "Parameters" and click the "Add Feature Parameter" button:

Removing a Feature

Remove the feature definition from both the Digital Thing Python code and the .bof file.

A feature can be removed by clicking its "Remove Feature" associated button:

Removing Function/Action Parameters

Update a feature definition by removing a parameter from its code and .bof file.

You can remove Function/Action feature parameters as you would delete an argument from a normal Python function. Once you click save, the Code Manager will take care of synchronizing the changes in the code to the Bill Of Features. See Auto Sync for more information.

Extension Output

You can view the output logs generated by DevOps by clicking the "IoT Catalyst DevOps" item in the VSCode status bar.

---

Commands

Here are described the commands provided by this extension.

Connect to a Remote Host

Connect via SSH to a Remote Host and open a VSCode window inside that host.

NOTE: once connected, it may be required to manually install again the DevOps extension inside the remote host. To do so, just follow the installation guide.

Select Hypervisor Folder

Lets you select the folder of a locally installed Hypervisor. Once selected, this information will be saved into the Visual Studio Code settings and the workspace will be reloaded. The prompt widget looks like the following:

See here for more information.

Select Container Folder

Lets you select a Container among the ones mounted on the selected Hypervisor, and opens the container folder in the VSCode workspace.

NOTE: This command is the prerequisite for all the DevOps commands that operate on a Digital Thing or a Container.

1. First of all, you will be prompted for a valid .

2. Then, select a container from the ones available on that Hypervisor:

   

3. Once selected, the container folder will be opened in your current workspace. The list of directories will look like this:

   

Create a new Digital Thing

Creates a new empty Digital Thing and uploads it to the IoT Catalyst library.

1. First of all, you will be prompted for valid Hypervisor Path and Credentials.

2. Then, select the blueprint you want to use for the Digital Thing:

   

3. Insert a name and a description for the Digital Thing.

   

4. Once inserted, the Digital Thing will be uploaded to the IoT Catalyst library and, if everything goes successfully, an information message like this will be shown:

   

Mount a new Container

This command creates a new Container starting from an existing Digital Thing and mounts it on the local Hypervisor.

1. First of all, you will be prompted for valid Hypervisor Path and Credentials.

2. Then, select the Digital Thing for the Container among the ones compatible with your Hypervisor:

   

3. Insert a name and a description for the Container.

4. Once inserted, a new Container will be provisioned to the IoT Catalyst Domain and the local Hypervisor will mount the Container. If everything completes successfully, the current workspace will switch to the newly created Container, and the Container will be available in your IoT Catalyst Domain.

Install Python Dependency

Lets you choose a Python package among the ones available on PyPi. Once selected, the package will be installed in the Python environment relative to the Container opened in the current Workspace.

NOTE: this should be the only way to add dependencies to a Digital Thing. Do not edit manually the requirements.txt in the container folder since it will be overwritten by the distribute script executed by the extension when you launch a command such as Upload Digital Thing to IoT Catalyst Library.

Compile Digital Thing Code

This command compiles the Python source files of the Digital Thing included in the Container Workspace, and puts the compilation artifacts in the digitalthing directory.

Upload Digital Thing to IoT Catalyst Library

Create the distributable zip bundle for the Digital Thing included in the Container Workspace and upload it to the IoT Catalyst library.

NOTE: the Digital Thing must have been previously created either via the IoT Catalyst Studio GUI or the Create a new Digital Thing command.

1. First of all, you will be prompted for valid Credentials.

2. Then, you will be prompted to insert a new description for the Digital Thing.

3. Once the operation completes, the Digital Thing zip bundle will be locally available inside <hypervisor path>/containers/dist. Additionally, the new version of the Digital Thing will be available in the IoT Catalyst library.

Deploy Changes to IoT Catalyst Library

Do the same as Upload Digital Thing to IoT Catalyst Library and also update the Bill of Features of the Container in the current workspace.

This command is meant to be used when you either add or remove a feature from a Digital Thing instantiated on a container, and would like to apply the changes to that container without the need of remounting it.

After this command completes, it is possibile to debug the Digital Thing Code using the updated container.

Debug Container

Restart the container in the current workspace in debug mode using the Python Debugger.

1. First of all, you will be prompted for valid Credentials.

2. Then, an information message at the bottom right of the page will prompt you to open the Container Detail page on IoT Catalyst Studio (optional). If you click on the given link, you will see the Container detail in the browser like the following:

3. From now on, you can use the VS Code editor to put breakpoints inside the Digital Thing main.py and debug as you would do with any Python script!

Open Local Container Details in IoT Catalyst Studio

This command will open a browser to the IoT Catalyst Studio Container details related to the Container in the current workspace.

---

Known Issues

Container fails to be unmounted if opened in VSCode

Do not unmount/update a container while its folder is opened in the Visual Studio Code workspace. Otherwise the hypervisor will encounter a Permission error while deleting the unmounted container folder.

Terminal Default Profile in Windows Environment

Make sure that your VSCode Terminal Default Profile is "Command Prompt". Otherwise some commands (such as Upload Digital Thing to IoT Catalyst Library) would not work because they invoke cmd scripts under the hood.

Please refer to this guide for more details.

SSH Remote: Troubles while connecting

If you get stuck in a loop while Connecting to a Remote Host: enable TCP Port Forwarding on the remote host.

Please refer to this guide for more details.

SSH Remote: VSCode Terminal not loading .profile

If when you connect to a Remote Host and the Visual Studio Code Terminal is unable to recognize some system executables (eg. pyenv) you may be able to fix it by deleting the ~/.vscode-server folder on the remote host and reinstalling the IoT Catalyst DevOps extension.

Please refer to this thread for more details.

Incompatible with WSL

The extension does not work if VSCode is opened inside WSL (Windows Subsystem for Linux), due to incompatibility issues related to launching system processes.

Missing support for type hints

Usage of Python type hints inside the Digital Thing code is not allowed, as it clashes with the DevOps Code Manager implementation (as of August, 2023).

---

For more information

• IoT Catalyst

Enjoy!