Xbit VSCode Extension

Canvas Software Suite includes a VS Code Extension called Xbit. This extension provides an easy interaction with Canvas Firmware compatible DVKs and IoT products for loading python scripts to the device and interacting with the python REPL prompt.

Features

1. Read, Write, Rename, Delete python files on supported boards.
2. Psuedo-terminal integration for interactions with the MicroPython REPL on supported boards.
3. Auto-completion and docs for supported Micro Python libraries.
4. Virtual-workspace provider for supported boards.
5. Development environment for Xbit Applets.
6. Write firmware .hex images to supported boards.

Requirements

• Canvas Device
• Python 3.11 or newer
• Pip 22 or newer
• On Linux, you may need to install the python venv package. On Ubuntu, this can be done with the following command: sudo apt install python3.11-venv

Visual Studio Code extensions:

• ms-python.python | Install Show
• visualstudioexptteam.vscodeintellicode | [Install] [Show]
• ms-python.vscode-pylance | [Install] [Show]

Getting started

Opening VS Code should automatically display the Xbit extension icon in the sidebar when installed. When the Xbit extension is activated by clicking on its icon, it will scan your workstation for compatible USB devices and present a USB serial port list in the sidebar. If a Python REPL is detected, you will see a name next to each device serial port and an icon indicating the type of interface available. A triple greater-than '>>>' icon indicates a Python REPL prompt.

If a USB serial port is detected but the identity of the port cannot be determined, you’ll see a generic device listing identified by the default icon. At any time you can refresh the list of devices by clicking the refresh button in the USB DEVICES header bar. If the device's name indicates that the device is busy, it is likely that the device is already connected to another application. You will not be able to interact with the device until the other application releases the device.

This extension will also allow interaction with Zephyr console shells on devices that support it, though these are hidden by default. Enable Zephyr shell in the extension options to see them. A Zephyr shell is indicated by a '$~' icon. If a Zephyr shell is detected, you can click on the device name to open a terminal window and interact with the shell.

Updating Canvas Firmware

This extension supports use of PyOCD to program firmware to supported boards. You will need to setup a Python virtual environment to support Python-based operations. To do this, open the command palette (CTRL+SHIFT+P) and find "xbit: Initialize Python Environment". When prompted, select a location for the tool to store its virtual environment. The tool will create its own subfolder named xbit.venv in the folder you select and operate from there. If your system doesn't meet the minimum requirements for python, the tool will prompt you to install the missing requirements.

Canvas Firmware is the underlying software enabling Canvas-enabled radio modules to run Python scripts and access underlying hardware via APIs. It is important to make sure your hardware is using the latest Canvas Firmware before you start developing application scripts. See the product page for details on where to locate the latest Canvas Firmware for your specific hardware.

Boards supporting PyOCD with a Canvas firmware image available as a .hex file can be programmed right from within the Xbit VS Code extension. To program a .hex file to the board, right-click on the REPL port in the USB DEVICES panel and select Write Hex File. Once clicked, a file selection dialog will appear where you can select the desired .hex file to program onto your device.

Interacting with the Device’s Python REPL

When interacting with a device, you can Connect or Disconnect from the associated USB serial port. When the port is connected, the icon for the device will be highlighted in blue. The Xbit user interface panel has a header displaying SELECTED DEVICE providing a few options for interacting with the device including a Connect/Disconnect button. Pressing the Connect button will bring up a Terminal within VS Code that you can press Enter to interact with. To access the Python REPL of the device, select the serial port displaying the 3 greater than symbol >>> in the USB DEVICES panel, then click the Connect button down below. This will open a new terminal to the selected device that you can use to interact with the Python REPL.

Working With Files

Files are stored in a virtual filesystem while working in VS Code. If files are changed on the device outside of VS Code, you can refresh the device (or individual file) by right-clicking on the item and selecting 'Refresh' to reload the files into VS Code. If xbit.venv folder is configured, a backup copy of all files that you open/edit from devices will be stored in the xbit.venv folder.

Creating a Python Script on a Device

To create a Python script directly on the filesystem of a compatible device, right-click the name of the device that lists the serial port of the board you’d like to interact with and select Create File.

You will then be prompted for a file name to create on the device.

Type the name of the file you’d like to create such as hello.py and then press Enter to create it.

Editing Python Files on a Device

To open and edit a file on your device, single click the file of interest in the device view to load it into an editor panel. You can then type directly into the text editor to modify the contents of the file. When you save the file, it will be saved back to the device's filesystem.

Renaming a Python Script on a Device

To rename a file such as a Python script already on your device, right click the file in the device view and select Rename File.

You will then be prompted for the new name you would like to assign to the file. enter the new name and press Enter to rename the file.

Deleting All Files on a Device

By right-clicking on the USB device you can delete all files and folders on the device filesystem. You will be asked for confirmation before deleting all files.

Backup and Restore

The Xbit extension provides backup and restore functions for automatic file backup as well as full backup and restore of the device filesystem.

Automatic File Backup

In the Xbit extension settings you can enter a local path where files are being automatically saved simultaneously when they are saved to the device file system. The extension will create a folder named after the device id for each device used.

You can also enable adding a timestamp to each saved file which will give you

Backup Full Filesystem

You can also backup the full filesystem into a local folder. It will prompt you for a local folder and will replicate all files and folder there. Existing files/folders will be overwritten and it will not delete files in advance.

Restore Full Filesystem

Similar to the above filesystem backup you can also restore the device filesystem from a local folder. It will ask for confirmation to delete all device files before and then prompt to select the folder to restore from.

Intellisense

This extension comes with intellisense support for the Canvas MicroPython libraries. To enable intellisense, open a workspace and right click on any file. Select the "Xbit: Initialize Workspace..." option. The .vscode folder will be created in the workspace and the necessary files will be created.

You can now open a python file and start typing. Intellisense will provide suggestions for the current word. You can use the arrow keys to select the desired suggestion and press Enter to insert it into the editor.

Running Python Scripts on a Device

When viewing the files on a device, you can right click on a python script and select Run File to execute the script on the device. The output of the script will be displayed in the output window.

Troubleshooting

Serial Port Unavailable or Busy

If you are unable to connect to a device and see an error like this, double check if another application is already connected and using the port. If not, the serial port may be in an error state. This may be fixed by unplugging the device and plugging it back in.

Timeout Errors

These will occur if the extension doesn’t get a response from the connected device. This usually means that the REPL console is in a state where it can’t process commands. Try to manually connect to the device to see it the REPL prompt is displayed. See Interacting with the Device’s Python REPL. If you are unable to get a REPL terminal unplug the device and plug it back in, click the refresh button to redetect the devices.

Using Xbit Applets

This extension supports working with Xbit Applets. Xbit Applets are a way to develop and deploy desktop applications for Canvas Devices. Xbit Applets are written in Javascript. These applets typically provide a user interface to interact with the device. They can also be used to pipe data from the device to the applet for logging or other purposes.

1. Connect a Canvas Device to your computer.
2. Open an Xbit Applet folder in your VS Code workspace.
3. Find the package.json file for the applet you want to run, right click and select "Run Xbit Applet..."
4. Switch to the Xbit extension and find the device you want to use for the applet.
5. Connect to the device.
6. In the lower "selected device" panel, from the drop down "selected applet" choose the running applet to pipe device data to the applet.
7. To stop sending data, change the drop down to "none"