Sublime Text 3 plug-in for Electric Imp applications development.
The Plug-in is designed to improve developer productivity. 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, including navigation to the file and line in question
- Key shortcuts for frequent operations (build and run, show console, etc.)
- Leverages Sublime Text 3’s rich set of features.
The Plug-in requires connection to the Internet as it leverages the Electric Imp impCentral™ API to work with the Electric Imp impCloud™.
Note The Electric Imp Sublime Plug-in supports Sublime Text 3 only. No other versions are supported. Tested on macOS only.
Note The plug-in requires Node.js 4.0 or above.
Please follow these instructions to install Node on your machine.
The plug-in uses the Builder Node.js module for source code pre-processing. To install Builder, please use Node Package Manager (NPM):
npm i -g BuilderSublime Text 3 can be downloaded for a variety of platforms, here.
If you already have Package Control installed in Sublime Text:
- Select
Install Packagefrom the Command Palette: Ctrl+Shift+P on Windows and Linux or ⌘⇧P on macOS - Search for Electric Imp Developer and click Enter
- Restart Sublime Text 3
You can install the plug-in with the following command in the Sublime Text terminal (ctrl+` ) which utilizes git clone.
Note Please make sure you have git installed on your system when trying this method.
import os; path=sublime.packages_path(); ie_plugin_path=os.path.join(path, 'imp-developer'); (os.makedirs(path) if not os.path.exists(path) else None); window.run_command('exec', {'cmd': ['git', 'clone', 'https://github.com/electricimp/ElectricImp-Sublime.git', 'imp-developer'], 'working_dir': path}) if not os.path.exists(ie_plugin_path) else window.run_command('exec', {'cmd': ['git', 'pull'], 'working_dir': ie_plugin_path})Alternatively, follow these steps to install the plug-in manually:
-
Create the plug-in folder:
- macOS /Users/<username>/Library/Application Support/Sublime Text 3/Packages/imp-developer
- Windows "%AppData%\Sublime Text 3\Packages\imp-developer%"
-
Do one of the following:
- Download the full GitHub source repository as a .zip file and extract its contents into the plug-in folder (Sublime Text 3/Packages/imp-developer) or
- Clone the contents of the source repository ElectricImp-Sublime into the plugin folder (Sublime Text 3/Packages/imp-developer)
- Restart Sublime Text 3
Your first step should be the creation of a new project. Do this by selecting the ‘Tools’ > ‘Packages’ > ‘Electric Imp’ > ‘Create Project’ menu item. You will then be asked to specify the project folder.
The project folder will be set up with the following:
-- <Project Name>
|--> settings - Electric Imp settings folder
. |--> auth.info - SENSITIVE: impCentral API tokens and
. | GitHub authentication information
. |--> electric-imp.settings - Generic Electric Imp settings
|--> src - Source folder
. |--> device.nut - Device code
. |--> agent.nut - Agent code
|--> .gitignore - .gitignore file to exclude auth.info file
| from git repository
|--> electric-imp.sublime-project - Sublime project file
Important settings/auth.info should not be put under source control as it contains sensitive information
The electric-imp.settings file contains:
- A unique project identifier.
- A unique Device Group identifier.
- The most recent deployment made by the plug-in.
- Device and agent code file names.
- Builder preprocessor configuration
- The impCentral API base URL (can be changed to work with private impClouds)
{ "product-id" : "<product id>",
"devicegroup-id": "<device group id>",
"deployment-id" : "<deployment id>",
"device-file" : "<path to device source file, src/device.nut by default>",
"agent-file" : "<path to agent source file, src/agent.nut by default>",
"cloud-url" : "<impCentral base endpoint URL>",
"builder-settings": { "variable-definitions": {<Builder variable definitions>},
"builder_cli_path": "<Path to the Builder's cli.js>",
"node_path": "<path to Node.js (node) executable>" },
}
When a project is created, empty device and agent code files (device.nut and agent.nut) are automatically created
and stored in the <Project Name>/src folder.
If a project is created successfully, a new window with the project folder is opened.
Note If you need to apply the Squirrel language syntax highlighting to files with extension other than .nut, please make sure you have ‘Squirrel (Electric Imp)’ language selected under the ‘View’ > ‘Syntax’ menu item.
Important The code which is deployed to the Device Group is preprocessed and contains line control markers. When you select an existing Device Group, the plug-in pulls down the code, but it doesn’t transfer the project file/folder structure. So for collaborative work on the same project, please share the original Electric Imp plug-in project sources/structure via a source control system.
To open an existing Electric Imp project, select the ‘Project’ > ‘Open Project...’ menu option and choose the
<Project Name>.sublime-project file from your project folder.
Note The plug-in won’t properly detect an Electric Imp project if it is not opened as described, ie. if it is opened as a folder (‘File’ > ‘Open...’), not as a Sublime Text project.
To build and deploy code, please select the ‘Tools’ > ‘Packages’ > ‘Electric Imp’ > ‘Build and Run’ menu item. This action uploads the agent and the device code to the server, and restarts all of the devices assigned to the target Device Group.
When you first build code (or perform any other action that requires access to the impCloud), you will be asked to provide:
- The impCentral API base URL. The default value should be used, unless you are working with an Electric Imp Private impCloud.
- The path to the Node.js executable (if not automatically detected by the plug-in).
- The location of the Builder cli.js command line tool (if not automatically detected by the plug-in).
- Your Electric Imp account user name, password and one-time password (OTP) as needed.
- Whether the tool should create a new project or open an existing one.
- A Product that belongs to another user who has granted your appropriate collaborator roles.
- Whether the tool should create a new Device Group or select an existing one.
- You may also be offered the opportunity to download the latest deployment if you select an existing Product and Device Group.
If you want to have you code running on a specific devices and view the logs from that devices, you need to select them using the ‘Tools’ > ‘Packages’ > ‘Electric Imp’ > ‘Assign Device’ menu item. The ‘Unassign Device’ menu item removes a device from the project’s Device Group.
Note To build and deploy your code it isn’t necessary to assign a device to the Device Group. If you don’t have a device assigned, you can still work on the code and see compilation errors reported by the server.
The Console can be popped up by selecting ‘Tools’ > ‘Packages’ > ‘Electric Imp’ > ‘Show Console’ menu item. The Console shows live logs streamed from the current Device Group if the group contains at least one device.
To assign devices to the project’s Device Group, go to the ‘Tools’ > ‘Packages’ > ‘Electric Imp’ > ‘Assign Device’ menu item and select a device from the list. The newly added device is automatically attached to the console log stream.
Devices can be removed from the project’s Device Group by selecting the ‘Tools’ > ‘Packages’ > ‘Electric Imp’ > ‘Unassign Device’.
Note The log will be restarted when a device is unassigned.
The URL of a device’s agent can be retrieved by selecting the ‘Tools’ > ‘Packages’ > ‘Electric Imp’ > ‘Get Agent URL’ menu item. The URL is saved to the clipboard.
Note Electric Imp-specific menu items are only available if an Electric Imp project is opened in the currently active window.
| Command | Keypress |
|---|---|
| Create Project | Ctrl + Shift + Y |
| Build and Run | Ctrl + Shift + X |
| Show Logs Console | Ctrl + Shift + C |
Please refer to the Builder documentation for more information on the preprocessor syntax that you can use in your Squirrel code.
Please use the project <Project Name>/settings/auth.info file to specify your Builder GitHub authentication information:
{ ...
"builder-settings": { "github-user": "GitHub user name",
"github-token": "Personal access token or password" }
}
Please use the project <Project Name>/settings/electric-imp.settings file to specify the Builder variables definitions:
{ "builder-settings": { ...,
"variable-definitions": { "key1": "value1",
"key2": "value2" },
... }
}
The Electric Imp Sublime Plug-in is licensed under the MIT License.