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. Virtual-workspace provider for supported boards.

Requirements

• Canvas Device

Recommended Visual Studio Code extensions:

• ms-python.python | Install Show
• visualstudioexptteam.vscodeintellicode | [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.

Installing Canvas Firmware

This extension is designed to operate with Ezurio products running Canvas Software Suite firmware. Canvas firmware allows 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 Canvas Firmware GitHub page for the latest Canvas Firmware files for your specific hardware.

Interacting with the Device's Python REPL

NOTE: By default, scanning for devices and/or connecting to them will cancel a running Python program on the device. This will affect all Python devices connected to the system. Use the xbit-vsc.safe-discovery option in the extension settings to prevent sending a interrupt character (ctrl+c) during discovery and connection. This will allow you to connect to a device without interrupting a running program, but it may also result in reduced functionality until the REPL becomes available.

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.

Port Auto-Reconnect

Xbit includes a port monitor that can automatically reconnect previously connected devices if they are unplugged and plugged back in.

• When enabled, Xbit tracks connected devices and watches for their serial ports to reappear.
• If the same device/port becomes available again, Xbit attempts to restore the connection automatically.
• You can enable or disable this behavior from the Command Palette:
  • Xbit: Enable Port Auto-Reconnect
  • Xbit: Port Monitor & Reconnect Status

Related extension settings:

• xbit-vsc.portMonitor.enabled (default: true)
• xbit-vsc.portMonitor.pollingInterval (milliseconds, default: 500)
• xbit-vsc.portMonitor.maxReconnectAttempts (default: 3)
• xbit-vsc.safe-discovery (default: false, sends \r only for discovery/connect prompt checks)

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 a local backup path is configured (xbit-vsc.local-backup-path), a backup copy of all files that you open/edit from devices will be stored in that 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.

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.