As its name suggests, the Workspace is where the bulk of your work is done. It changes depending on which Tab Bar tab you select. Here’s we’ll focus on working with code, which you access from the ‘Models’ tab.
Move your mouse pointer over a model in the ‘Model’ tab’s list then click on the Code icon () in the ‘Actions’ column. The model’s agent and device code will now appear in the Workspace alongside each other, ready for editing. Because agent and device code work together closely, they are always presented together, though it is possible to hide either pane temporarily by dragging the line that separates them to the left or to the right.
Alternatively, click on the devices icon in the top bar and locate a device running the model you want to view. Click on the Code icon () in the ‘Actions’ column for that device.
The Workspace in model mode presents the models name and its own tab bar. You’ll always see a ‘Code’ tab; if you’re an Electric Imp Customer you may also see ‘Factory’ and ‘Report’ tabs if you’re viewing a production model. If you’re viewing a shared account’s model, which Workspace tabs you see will again depend on your collaboration role.
Below the tabs are a set of model control buttons: some trigger actions, others pop up menus, and some are only available if you have appropriate permissions, either as the account owner or as a collaborator on a shared account. The device and agent code panes come next and, further down still, is a list of devices assigned to the selected model. Selecting a device allows you to view its log messages in the space to the right. If you’re working on a model with no devices assigned to it, ie. an inactive model, the device list will be empty.
Both agent code and device code panes present context-colored listings, with line numbers to help simplify debugging. The IDE recognizes pairs of braces,
}, whether they are part of the definitions of object classes or functions, or delimit blocks of code in control structures. Each pair of braces has a small disclosure triangle next to the line number of the first brace. Click this triangle to condense the code within the braces and to reveal it again:
Alternatively, clicking on the double-headed arrow icon which represents condensed code between braces also causes the code within to be displayed.
Double-clicking on either brace will highlight all the code between the braces. This is a handy way to spot instances where braces are unpaired.
The IDE uses the Ace code editor. Ace has many keyboard shortcuts — Alt-0 and Alt-Shift-0 to automatically fold and unfold pairs of all pairs of braces, for example — and you can find a full list of them here.
The IDE will automatically pair an opening brace with a closing brace to save you from having to key it in manually. It will automatically follow an opening round bracket,
(, with a closing round bracket,
), too. Similarly the IDE will add a double-quote symbol after to enter the first. If you highlight a section of text and hit the double-quote key on your keyboard, the IDE will place quote characters at both ends of the highlighted text.
The Workspace provides a way to test your code for simple syntax and typographical errors without deploying agent and device code to server and device, respectively. The ‘Check’ button triggers this process:
The ‘Check’ button appears in both device and model modes. Syntax check success or failure is signalled with, respectively, a green or red pop-up:
If the checker spots one or more errors in your code, they will be highlighted with a white-on-red X alongside the number of the line in which the IDE believes you have made a mistake. Moving the mouse pointer over the X presents the IDE’s reason for highlighting an error:
This is not always the exact point of error. For example, failing to complete the definition of a function with a closing brace will be signalled with an X at the end of your program. This is because the IDE doesn’t know how many of the intervening function definitions and code are meant to be in front of the missing brace and how many should come after.
Errors caused by using incorrect Squirrel or providing imp API methods with, for example, incorrect or mis-applied parameters, will not be detected by the syntax checker. To expose these errors, you’ll need to first build and then run your code.
When your model’s code is changed and then saved, it is called a ‘build’ and is assigned a new build number, starting at 1 and increasing by one with every save. The higher the build number, the more recent the version of the model. Saving either the agent code or the device code will establish a new build for that model.
You can see the current build number in the Workspace’s ‘Build’ menu (indicated by a small triangle). The menu says ‘Draft’ when you have not yet saved any code. An asterisk alongside the build number indicates there are unsaved changes for existing agent and/or device code:
The menu also lists the date and time at which each listed build was saved, and which user generated the build. If your account is shared with collaborators — or you are viewing an account on which you collaborate — you can use this menu to view who has made changes to the model:
If no device has been selected from the list at the bottom of the Workspace, you will see a button just below the model’s name that is titled ‘Build’, as shown above. Pressing it saves the code displayed in the Workspace as a new build and prepares it for use but doesn’t execute it. Neither your device nor your agent will be restarted to run the new code; they will not do so until you power-cycle the device. Upon restart, the device will detect there is a new version of its assigned model, then download and run it. Restarting the device prompts the agent to check for new code too.
It’s not necessary to power-cycle the device to get the new code to run. As we’ll see in ‘Run Your Code’, below, the IDE can trigger this for you.
If you need to go back to an earlier build, perhaps because you were unhappy with changes you or a collaborator made, just click on the ‘Build x’ menu and you’ll see a list of the most recent 20 builds and an option that allows you to select earlier builds if there are any. Select a build, and the IDE will display its agent and device code in the Workspace.
Previous builds can’t be edited — the headers of both the agent and the device code panes will be marked ‘Read Only’ and a lock icon is superimposed on the code — but viewing one adds a ‘Copy to New Build’ button to the Workspace. Clicking on this creates a new, unsaved draft containing the agent and device code from the earlier build that you just selected:
If the build you need is earlier than the 20 most recent builds, you can use the ‘Choose’ entry at the end of the ‘Build x’ menu:
Just enter the build number you want and hit Return on your keyboard or click on the menu’s folder icon. The requested build will appear in the Workspace.
Though previous builds can’t be edited, you can highlight and copy portions of code and manually paste them into the current build. This can be handy if you just need to recover an earlier version of a particular part of your program, such as a function or a class.
Whenever you copy a previous build in its entirety to a new build, if you have unsaved changes in the current draft, the IDE will warn you. If you click ‘Overwrite’ any changes made to the current draft will be lost. Clicking ‘X’ allows you to go back and save the draft as a new build, n, and you can then go back and copy the earlier version as build n+1.
All of the development devices assigned to a model are listed below the two code panes:
Each device assigned to the model is listed along with the account with which the device is associated: this can be useful if you are working as a collaborator on a shared model. To the right of each model is a gearwheel icon () — click on this to open the device’s ‘Device Settings’ panel. Here you can re-assign the device to a different model.
If you’re unsure which model your chosen device is currently running, enter its name in the search field at the right of the Tab Bar:
When you can see your device, click on its gearwheel icon () to open ‘Device Settings’ and assign it to the new model. The code icon () will take you to the device’s code if it has been given any already.
Selecting a device in the code view presents the device’s latest log messages (see below) in the panel to the right of the device list. Above the log, you’ll see device and agent status information — whether either or both are online or offline — along with the agent’s URL. The URL is a live link, so you can click it to visit the agent in a web browser:
When you have selected a device, you will see a third pane to the right of the device list. This panel displays messages logged by the agent and the device. Logged messages are presented in date order, the most recent at the bottom. Only the most recent messages are available to view at any one time, up to a limit of 200 messages:
At the top right of the log pane, you’ll see a set of controls. The first control allows you to clear the log pane. This is only temporary; the log messages are not deleted. If you switch to another device and then back to the original device, the latest log messages will re-appear.
The second control () mutes logging (and unmutes logging on a second click). Again, log messages are not lost, they are simply not presented by the IDE. This can be useful if your device is issuing many messages in short spaces of time.
The lock control () prevents the log pane from automatically scrolling upward as new messages are posted. Again, this can be useful if your device is issuing many messages in short spaces of time but the one you are interested in has been moved out of the log pane: just lock the log and use the scrollbars to locate the message you want to read.
When you have selected a device, you’ll see the model’s ‘Build’ button becomes ‘Build and Run’. Click this to force your development device to restart and thus download its portion of the updated model, and the agent to restart and run the latest agent code. When the device reboots and reconnects to the Electric Imp impCloud™, it is automatically sent new application software if any more recent code is available. This process also causes the device’s agent to restart, again loading new code if it is available.
To run your code on the selected development device immediately, click on the ‘Build and Run’ button. If you’re viewing a model but have yet to select one of its devices, the ‘Build and Run’ button reads simply ‘Build’. Clicking on it causes the code in the two listing to be uploaded to the impCloud as with ‘Build and Run’, but none of the model’s will restart automatically to acquire the updated code. If they’re subsequently restarted manually — for example, by power-cycling — they will gain the new code at that time. To restart a specific device through the IDE, select the device from the list in the model view and click on ‘Build and Run’.
The IDE will now check your code, signalling success or failure with a green or red pop-up:
If there syntax errors, look for the white-on-red Xs among the listings’ line numbers.
If the code passes the syntax check, the IDE deploys the code to the server: it is ‘staged’ ready for the next time the device restarts. If you click ‘Build and Run’, that restart is initiated automatically. Watch the logs for status messages informing you of the progress of the deployment. If your code contains Squirrel errors, these will be reported in the log too.
If you have more than one device assigned to the model you have just built and run, only the currently selected device is now running the new code. The others are still running the previous build and will do so until they are either power-cycled or you select each one and click on the ‘Build and Run’ button.
In summary, development devices only download and run staged model code updates (and their agents receive and run staged agent code) when they restart or reconnect to the impCloud. The ‘Build’ button simply stages updated code for all devices assigned to that model. The ‘Build and Run’ button (only visible when a device is selected) stages updated code for all devices assigned to that model and restarts the selected device only.
The Workspace contains two orientation buttons, a settings button and a zoom button toward its far right-hand side:
The first two of these buttons allows you to switch between the Workspace’s two pane-stacking modes: horizontal, with the agent code pane on the left and the device code on the right, or vertical, with the agent code pane on top of the device code pane.
In either orientation, the dividing line between the two panes can be moved manually to increase the space available to display the code in either pane, though neither can be completely removed from the Workspace so that you can quickly move back to the hidden code when you need to.
Clicking on the settings button alongside the orientation buttons calls up the ‘IDE Settings’ panel. Here you can configure the panes to represent code indentation tabs as a distance of either two or four space characters. You can also select the workspace theme:
The themes available are ‘light’ and ‘dark’:
If you need to focus on code and the user interface is proving a distraction, clicking on the zoom button will cause the workspace to fill the browser window, temporarily hiding the IDE’s navigation features.
In this mode, the expansion button becomes a contraction button; clicking this will restore the full UI.