Electric Imp impCentral Microsoft Visual Studio Code Extension

Contents

• Overview
  • Requirements
• Installation
  1. Install Node.js
  2. Install The Builder Node.js Module
  3. Install Visual Studio Code
  4. Install The Visual Studio Code Extension
• Extension Commands List
• Visual Studio Code Extension Usage
  • Create A New Project
  • Open An Existing Project
  • Build And Run Code
  • The Log Console
  • Assign A Device To The Project Device Group
  • Unassign A Device From The Project Device Group
  • Retrieve An Agent URL
  • Extension Keyboard Shortcuts
• Pre-processor And Multiple File Support
  • Specify GitHub Authentication Information
  • Specify Builder Preset Variable Definitions
  • Include Builder JavaScript Libraries

Overview

This Extension for the Microsoft Visual Studio Code text editor enhances Electric Imp application development by delivering access to the Electric Imp impCloud™ via the Electric Imp impCentral™ API. It allows you to rapidly build and maintain applications by providing:

• Code auto-completion for Electric Imp’s imp API.
• The ability to use a source control system to manage application code and configuration.
• Advanced Squirrel code highlighting.
• Integration with impWorks™ Builder to enable multi-file projects and code pre-processing.
• Live logs with clickable stack traces for errors, and navigation to the file and line in question.
• Key shortcuts for frequently performed operations (build and run, show console, etc).
• Leverages Visual Studio Code’s rich set of features.

Requirements

For operation, the Extension requires a connection to the Internet. It also requires Node.js, impWorks Builder and Visual Studio Code.

Installation

1. Install Node.js

The Extension requires Node.js 11.0 or above. Please follow these instructions to install Node on your machine.

2. Install The Builder Node.js Module

The Extension uses the Builder Node.js module for source code pre-processing. To install Builder, please use Node Package Manager (NPM):

npm i -g Builder

3. Install Visual Studio Code

Visual Studio Code can be downloaded for a variety of platforms here.

4. Install The Visual Studio Code Extension

It is recommended to install the Electric Imp Visual Studio Code Extension from the Visual Studio Marketplace.

The Visual Studio Marketplace can be accessed through Visual Studio Code itself. Please refer to the Marketplace documentation for more details. Search for the extension using "Electric Imp Squirrel" and, when the extension is listed, click the Install button next to it in the search results.

Extension Commands List

The Extension provides the following commands:

• imp: Auth User Password — Create an authorization file with a new access token in the selected workspace directory.
• imp: New Project — Create a new project (configuration and source code files) in the selected workspace directory.
• imp: Deploy Project — Deploy the source code to the selected Device Group and restart the group’s devices.
• imp: Start Device Logs — Start showing logs from a device in the console output.
• imp: Stop Device Logs — Stop showing logs from a device in the console output.
• imp: Pause Logs — Pause the logs in the console output.
• imp: Clear Logs — Clear the logs in the console output.
• imp: Add Device to current DG — Add a device to the workspace Device Group.
• imp: Remove Device from current DG — Remove a device from the workspace Device Group.
• imp: Get agent URL — Display a device’s agent URL.
• imp: Show All Commands... — Show the list of Extension commands.

Visual Studio Code Extension Usage

Create A New Project

Select a new project working directory using File > Open Folder..., if you have not done so. Select the View > Command Palette... > imp: New Project menu item.

When you create new project (or perform any other action that requires access to the Electric Imp impCloud), you will be asked to:

• Provide your impCentral API base URL. The default value should be used, unless you are working with a Private impCloud.
• Provide your Electric Imp account user name, password and one-time password (OTP) as needed.
• Select an impCentral account for the project from a list of accounts available for the user. Please see ‘impCentral Collaborator Account Access’ for more details.
• Specify whether a new Product should be created or an existing one selected for the project.
• Specify whether a new Device Group should be created or an existing one selected for the project.
• Choose what to do with sources: download them from the chosen DG, make them blank or leave them as is (if already exist)

The project directory will be set up with the following files and structure:

<project working directory>
  |----> settings                   - Settings directory
  .   |--> auth.info                - SENSITIVE impCentral API tokens and 
  .   |                               GitHub authentication information
  .   |--> imp.config               - Generic Electric Imp settings
  .
  |----> src                        - Source code directory
  .   |--> device.nut               - Device code file
  .   |--> agent.nut                - Agent code file
  .
  |---->.gitignore                  - .gitignore file to exclude auth.info file 
                                      from git repository

IMPORTANT The file auth.info in the settings sub-directory should not be put under source control as it contains sensitive account information. A .gitignore file is included automatically to prevent this.

The imp.config file contains:

• Electric Imp impCloud URL
• A unique user identifier.
• A unique Device Group identifier.
• Device and agent code file names.
• Builder settings (also, see more below):
  • Variables.
  • JavaScript libraries.

Example

{
  "cloudURL"       : "<Electric Imp impCloud URL>",
  "ownerID"        : "<user ID>",
  "deviceGroupId"  : "<device group ID>",
  "device_code"    : "<path to device source file; src/device.nut by default>",
  "agent_code"     : "<path to agent source file; src/agent.nut by default>",
  "builderSettings": {
    "variable_definitions": {
      "<variable 1>": <value 1>,
      ...
    },
    "builder_libs": [
      "<path to Builder js library 1>",
      ...
    ]
  }
}

When a project is created, device and agent code files (device.nut and agent.nut, respectively) are automatically created (if not exist yet) and stored in the project working directory’s src sub-directory.

Important Notes

• If the project working directory is not open in Visual Studio Code, no Extension commands will work. Use File > Open Folder... to open the directory.
• The code which is deployed to a Device Group is pre-processed and therefore may contain line control markers.
• If you choose to download the code currently deployed to the Device Group, the Extension downloads the code but doesn’t transfer it to the project file/directory structure.
• If you are working with collaborators on a project, please share the original Electric Imp Extension project sources/structure via a source control system.

Open An Existing Project

To open an existing project, use File > Open Folder... to open the project working directory.

Build And Run Code

To build code and deploy it, use View > Command Palette... > imp: Deploy Project.

This action pre-processes and then uploads the agent and the device code to the impCloud™ server. Finally, it restarts all of the devices assigned to the target Device Group.

If you want to run your code on specific devices and view the logs from those devices, you need to select them using View > Command Palette... > imp: Add Device to current DG. The imp: Remove Device from current DG command removes a device from the project’s Device Group.

Note It isn’t necessary to assign a device to the Device Group to build and deploy your code to the group. If you don’t have any devices assigned to the Device Group, you can still work on the code and see any compilation errors reported by the server.

The Log Console

Live logs from devices are streamed to the console that is displayed by selecting the View > Output menu item. It is possible to add a specific device to the live logs by its ID using the View > Command Palette... > imp: Start Device Logs command. To stop showing logs from a specific device use the View > Command Palette... > imp: Stop Device Logs command. The console shows live logs streamed from the current Device Group if the group contains at least one device.

Also you can pause the logs (using the View > Command Palette... > imp: Pause Logs command) and clear the logs (using the View > Command Palette... > imp: Clear Logs command).

Assign A Device To The Project Device Group

To assign devices to the project’s Device Group, select View > Command Palette... > imp: Add Device to current DG.

Unassign A Device From The Project Device Group

Devices can be removed from the project’s Device Group by selecting View > Command Palette... > imp: Remove Device from current DG.

Retrieve An Agent URL

The URL of a device’s agent can be retrieved by selecting View > Command Palette... > imp: Get agent URL. The URL is displayed in a dialog box and copied to the clipboard.

Extension Keyboard Shortcuts

Note Electric Imp-specific menu items are only available if an Electric Imp project is open in the currently active window.

Pre-processor And Multiple File Support

Please refer to the Builder documentation for more information on the pre-processor syntax that you can use in your Squirrel code.

Specify GitHub Authentication Information

Please use the <project working directory>/settings/auth.info file to specify your Builder GitHub authentication information:

{ ...,
  "builderSettings": { "github_user"  : "GitHub user name",
                       "github_token": "Personal access token or password" }}

Specify Builder Preset Variable Definitions

Please use the <project working directory>/settings/imp.config file to specify Builder variable definitions (as described here).

{ "builderSettings": { ...,
                       "variable_definitions": { "IntType": 34,
                                                 "FloatType": 34.456,
                                                 "ExponentType1": 3E4,
                                                 "ExponentType2": 3e-2,
                                                 "StringType1": "str1",
                                                 "StringType2": "\"str2\"",
                                                 "BoolTypeTrue": true,
                                                 "BoolTypeFalse": false,
                                                 "NullType": null },
                                        ... }}

It is possible to obtain these Builder variable definitions values from Squirrel code this way:

server.log(@{IntType});       // 34
server.log(@{FloatType});     // 34.456
server.log(@{ExponentType1}); // 30000
server.log(@{ExponentType2}); // 0.03
server.log(@{StringType1});   // str1
server.log(@{StringType2});   // "str2"
server.log(@{BoolTypeTrue});  // true
server.log(@{BoolTypeFalse}); // false
server.log(@{NullType});      // (null : 0x0)
server.log(@{NotDefined});    // (null : 0x0)

Include Builder JavaScript Libraries

Please use the <project working directory>/settings/imp.config file to include Builder JavaScript libraries (as described here).

{ "builderSettings": { ...,
                       "builder_libs": ["my_builder_lib.js", "another_builder_lib.js"]}}

License

The Electric Imp Visual Studio Code Extension is made available under the MIT License.