Particle Workbench

Workbench Features

Left Toolbar

Typically, there is a toolbar on the left with frequently used features.

Button Purpose
File Explorer
Search and Replace
Source code control (like Git)
Source level debugger
Add or modify VS Code Extensions
Particle Welcome Screen

Welcome Screen

Welcome Screen

The Welcome Screen has handy tips for using Workbench. If you close it, you can get it back by clicking on the Particle icon in the left toolbar.

Particle Commands

If you’re new to Visual Studio Code, the Command Palette will become a familiar part of the user interface. As the name implies, the Command Palette provides access to many commands such as open files, search for symbols, and see a quick outline of a file, all using the same interactive window. It can be invoked via cmd+shift+p on macOS or ctrl+shift+p on Linux and Windows.

Workbench adds custom Particle commands to the palette. Start typing Particle to see all the currently available commands.

Command Palette

Dependency Manager

Downloading and maintaining a local toolchain can be a full-time job so Workbench introduces a new dependency manager. It downloads the Device OS, build system, compiler, and anything else needed to develop and debug Device OS apps, and places them in a local, private location in user space as to not mess with your current configuration.

You can install and uninstall different versions of Device OS (and dependencies) with Particle: Install Local Compiler. You can uninstall unneeded versions just as easily.

Dependency Manager

Working with Particle Projects

You can initialize a new project with the command, Particle: Create New Project. Doing so will open a new a Visual Studio Code Workspace, an abstract concept of a collection of files and folders. The Workspace will include a scaffold of what is needed to begin developing your Particle project, like Tasks, C++ IntelliSense, Commands, files and folders. Note that these are designed to only work when editing Particle projects as to not muddy up the rest of your editing experience.

A project contains a number of files. Here's what's in a small sample project:

Project Directories

  • The .vscode directory contains your project-specific settings. The settings.json file allows you to override any setting on a per-project basis. It's also where your build firmware version, target platform, and target device are saved.
  • The src directory contains your source file. If you created a .ino file for your main project file, after building you may see a .cpp file of the same name. This is because the .ino file is transformed into a .cpp before compiling. You can create multiple source files and header files in this directory.
  • Not pictured here is the libs directory, at the same level as src. This contains the source to libraries that you have included. If you are cloud compiling, if you have the library listed in your project.properties file the cloud version of the library is used instead of the downloaded one in libs.
  • The target directory contains local build output. In particular, the .bin file (Test1.bin) is the same binary you get from downloading from the Web IDE or CLI.
  • The electron_firmware_1548790892661.bin (your filename will be different) at the top level is the result of a cloud compile for this project.
  • The project.properties file specifies all of the libraries that this project uses.
  • README.md is where you could put documentation for your project.
  • The .code-workspace is the workspace settings file for VS Code. There are no particle-specific settings in it.

If you already have an existing Particle project (with a project.properties file), you can import it to create the necessary VS Code files by using the command Particle: Import Project from the command palette.

Cloud build and flash

Before you can build in the cloud (the way Particle Web IDE, Particle Dev, and Particle CLI normally build), you need to select the device you wish to build for.

From the Command Palette select Particle: Configure Workspace for Device.

Configure Device

Then the device OS version you'd like to build for:

Configure Device

Then the type of device to you'd like to build for:

Configure Device

And finally the name or device ID of the device you want to flash to. You can leave this blank if you're going to flash by USB, or just want to test building.

Configure Device

To compile your program and download the binary, open the Command Palette and select Particle: Cloud Compile. To compile your program in the cloud and flash it to the selected device over-the-air, select Particle: Cloud Flash.

Compile or Flash

It's also possible to compile in the cloud and flash over USB, as described in the section Cloud build and flash locally, below.

Local build and flash

Local build does all of the compiling locally on your computer, and, once installed, can be used even without an Internet connection.

In order to target a specific version of Device OS you must install the appropriate toolchain first. From the Command Palette select Particle: Install Local Compiler.

Install Local Compiler

Then select the version you want to install.

Install Local Compiler Version

To compile and flash locally, use the Command Palette and select one of the local flash options:

  • Particle: Flash application (local)
  • Particle: Flash application for debug (local)
  • Particle: Flash application & Device OS (local)

Flash Local

In order to use the Flash options, the device must be connected by USB and in DFU mode (blinking yellow). Hold down the MODE (or SETUP) button while tapping RESET. Continue to hold down MODE (or SETUP) while the status LED blinks magenta (red and blue at the same time), until it blinks yellow, then release.

There are also compile options, which compile the code and download a binary:

  • Particle: Compile application (local)
  • Particle: Compile application for debug (local)
  • Particle: Compile application & Device OS (local)

Compile Local

Normally, Device OS (system firmware) is built by Particle and downloaded to your device if an upgrade is needed. User applications are generally small and fast to update because the Device OS is not normally downloaded.

With Workbench local builds, you can optionally flash both Device OS and your binary using the Flash application & Device OS option in Build Tasks. This will upgrade or downgrade the Device OS. It also allows you to make a modified Device OS and flash it to your device by USB.

There is also a monolithic build. It contains both the Device OS and your user application in a single binary. Using the for debug options creates a monolithic debug build. These binaries are large, but are better suited for use with the debugger. Also, because the boundary between Device OS and the user application is removed, it's possible to call more low-level system functions from monolithic builds.

The local compile and flash options are also available in the Build Tasks palette (cmd+shift+b or ctrl+shift+b).

If you are getting mysterious errors, sometimes it's helpful to do a clean to remove old objects that might be causing difficulties:

  • Particle: Clean application (local)
  • Particle: Clean application & Device OS (local)
  • Particle: Clean application for debug (local)

Clean Local

Compile and Flash Buttons

When you are viewing a .cpp or .ino file, there will be two new icons in the upper right corner:

Clean Local

Button Purpose
Compile
Compile and Flash

By default, the Compile button invokes Particle: Compile application & Device OS (local). Flash works similarly.

However you can make these buttons do other things, like cloud flash, by changing settings. From the menus, select Code > Preferences > Settings (Mac) or File > Preferences > Settings (Windows) and search for compileButtonAction and flashButtonAction to change the task to run when these buttons are used.

Compile Button Action

Integrated CLI

Workbench ships with a local copy of the Particle CLI (Command-Line Interface). The CLI powers many of the commands behind the scenes. It can also be accessed via the Integrated Terminal, which can be handy for features not yet exposed natively in Workbench. To open a CLI window, from the Command Palette enter Particle: Launch CLI.

In the Integrated Terminal window you can enter any Particle CLI commands, for example:

particle help
particle --version
particle libraries list

Integrated CLI

Cloud build and flash locally

Combining the cloud compile and integrated CLI, you can, for example, compile in the cloud and then flash to an Boron or Electron over USB to save on cellular data usage.

After you've done Particle: Cloud Compile you'll notice a new .bin file created in your workspace. In this example, it's electron_firmware_1548790892661.bin.

From the Command Palette enter Particle: Launch CLI.

The device must be connected by USB and in DFU mode (blinking yellow). Hold down the MODE (or SETUP) button while tapping RESET. Continue to hold down MODE (or SETUP) while the status LED blinks magenta (red and blue at the same time), until it blinks yellow, then release.

Then type in a command like:

particle flash --usb electron_firmware_1548790892661.bin

You can just type the first few letters of the filename then hit Tab to auto-complete the rest.

Local Compiler

Integrated Serial Monitor

One handy debugging technique is to use the USB debug serial port. Open the Command Palette and select Particle: Serial Monitor.

Normally, when the device restarts (such as after flashing new code) the serial port is disconnected, but you are presented with an option to automatically reconnect or not.

IntelliSense

Workbench leans heavily on the built-in IntelliSense features of Visual Studio Code and the C++ language support provided by the official C/C++ extension. Workbench works behind the scenes to automatically configures the C/C++ extension work with Device OS.

You can see IntelliSense in action by starting to type Particle. and see suggestions for public functions.

Intellisense

Or possible arguments.

Intellisense Arguments

IntelliSense for C++ includes a slew of advanced features for you to explore. For example, you can “peek” to the definition of a function.

Intellisense Peek

Particle Themes

Workbench includes two Particle-inspired theme to add a little pizazz to Workbench, Matter (by Particle) and Dark Matter (by Particle).

To change the color theme, open the Command Palette and select Preferences - Color Theme.

Themes

You can scroll through the list to try out the available themes, or select Install Additional Color Themes to select one from the Marketplace. There are a lot of them!

Keymaps

If you are used to a different development environment, you can use keymaps to switch the keyboard shortcuts to be similar to the other environment.

To change the keymap, open the Command Palette and select Preferences: Keymaps.

Some popular options include:

  • Vim
  • Sublime
  • Atom (Particle Dev is based on Atom)
  • IntelliJ
  • Visual Studio
  • Eclipse
  • Emacs

and many more!

Particle Libraries

Add one of the 3,000+ Device OS libraries with the Particle: Install Library command. Workbench will download the requested library, all its dependencies and even example projects.

Libraries

You can search for libraries from the command palette by using Particle: Find Libraries.

For example, I used the Particle: Install Library to install the AssetTrackerRK library. In the file navigation, you can see the two libraries that it included automatically, AssetTrackerRK and LIS3DH.

Navigating into AssetTrackerRK you can see the source and examples, and also the README.md file. That contains the documentation in most libraries.

Library Read Me

Snippets

Code snippets are templates that make it easier to enter repeating code patterns, such as loops or conditional-statements. We’ve included snippets for the bits of code we use most often for your Device OS apps. For example, start typing dw and hit tab to expand the snippet. You can tab between input entries, which includes suggestions.

Snippets

Debugging (3rd-generation)

For this tutorial, you'll use the TinkerBreak source. This is the same application used in the Eclipse Debug Tutorial. As you'll see, this is way easier in Workbench!

  • Create a new project using the Command Palette and Particle: Create New Project.
  • Rename TinkerBreak.ino to TinkerBreak.cpp. Paste in the TinkerBreak source into TinkerBreak.cpp.

Debug Workspace

  • From the Command Palette select Particle: Configure Workspace for Device and choose the Device OS and type of device you want to use.
  • Connect the Particle Debugger using the ribbon cable to your Argon, Boron, or Xenon device.
  • Connect the device to your computer by USB.
  • Click the Debug icon (1), then select the correct Debugger (2). In this case, it's Particle Debugger (argon, boron, xenon). Note that you need to select the type of device in both places!

Debug View

  • Hold down the MODE (or SETUP) button while tapping RESET. Continue to hold down MODE (or SETUP) while the status LED blinks magenta (red and blue at the same time), until it blinks yellow, then release.
  • Click the green arrow next to DEBUG in the upper left to build, flash, and begin debugging.
  • After flashing the device will typically halt. You can tell because the device status LED will go off.

Debug Console

  • Click Debug Console (1). The error shown is normal.
  • Click Continue (2). The device should boot up normally and get to breathing cyan.

You're now debugging the application!

  • From the Command Palette select Particle: Launch CLI. In the CLI window, enter a command like:
particle call argon2 break

Replace argon2 with the name of the device you're testing with. This should call a function via the cloud.

  • The command is entered in the Terminal tab (1).
  • Execution has stopped at the code breakpoint (2).
  • You can see the call stack (3).
  • You can continue execution using Continue (4).

Debug Console

You can also set your own breakpoints.

  • Scroll down to line 51. Click to the left of the line number so a red dot appears (1)
  • You'll also see it listed in the breakpoints tab (2).

Debug Break

  • From the Terminal window, enter a command like:
particle call argon2 div 10
  • Now you can see the execution has stopped (1). Sometimes it won't stop exactly on the line you put the breakpoint on.
  • The call stack (2) is much more interesting this time.
  • You can see the variables (3)!
  • When done, Continue (4).

Debug Breakpoint

That is just a brief introduction to debugging. For more information, see the VS Code Debugging Documentation.

Debugging (2nd-generation with Particle Debugger)

  • Create a new project using the Command Palette and Particle: Create New Project. If you already created a project for the 3rd-generation device, you can just reuse that one.
  • Rename TinkerBreak.ino to TinkerBreak.cpp. Paste in the TinkerBreak source into TinkerBreak.cpp.

Debug Workspace

  • From the Command Palette select Particle: Configure Workspace for Device and choose the Device OS and type of device you want to use. In this example, a Photon is used.
  • Connect the Particle Debugger to your device.

With the Particle Debugger positioned like this, USB connector toward you and the headers facing up:

Debugger

Left Header Right Header
VDD SWCLK
RTS SWDIO
RX NC
TX NC
CTS GND
GND VUSB

You need to connect:

Pin Function Color
GND GND Black
D7 SWDIO Green
D6 SWCLK Blue

Debugger

  • Connect the device to your computer by USB.
  • Click the Debug icon (1), then select the correct Debugger (2). In this case, it's Particle Debugger (photon, p1, electron). Note that you need to select the type of device in both places!

Debug Workspace

The rest of the instructions are the same as for 3rd-generation. Start with the putting your device in DFU mode step.

Migration Guide

From Particle Web IDE (Build)

One big change from the Web IDE is the lack of the icon bar on the left. Most replacements are available from the Command Palette (cmd+shift+p on Mac OS or ctrl+shift+p on Linux and Windows).

Button Label Replacement
Flash Command Palette Particle: Cloud Flash
Verify Command Palette Particle: Cloud Compile
Code You create a new app from the Command Palette Particle: Create New Project. If you use Particle: Cloud Compile the binary will be downloaded to the top level of your project so there isn't a separate download button. Since the files are already on your hard drive there is no project download button. Share this Revision is not supported in Workbench.
Libraries Command Palette Particle: Find Library and Particle: Install Library
Docs Go to https://docs.particle.io
Devices Command Palette Particle: Configure Workspace for Device
Console Go to https://console.particle.io

From Particle Dev (Atom IDE)

One big change from Particle Dev is the lack of the icon bar on the left. Most replacements are available from the Command Palette (cmd+shift+p on Mac OS or ctrl+shift+p on Linux and Windows).

Button Label Replacement
Compile in cloud and upload using cloud Command Palette Particle: Cloud Flash
Compile in cloud and show errors if any Command Palette Particle: Cloud Compile
Start a New Project Command Palette Particle: Create New Project
Browse and manage Particle libraries Command Palette Particle: Find Library and Particle: Install Library
Manage current library No replacement at this time.
Docs Go to https://docs.particle.io
Devices Command Palette Particle: Configure Workspace for Device
Console Go to https://console.particle.io
Show Serial Monitor Command Palette Particle: Serial Monitor.

Particle Dev Menu

  • The Log out menu item is replaced by the Command Palette Particle: Logout (and Particle: Login).
  • The Select device... meny item is replaced by the Command Palette Particle: Configure Workspace for Device.
  • The Claim device... menu item can be replaced by using the Command Palette Particle: Launch CLI and using the particle device add DEVICE_ID CLI command.
  • The Identify device... menu item done replaced by the Command Palette Particle: Launch CLI and using the particle nyan DEVICE_NAME CLI command.
  • The Compile in Cloud menu item is replaced by Command Palette Particle: Cloud Compile.
  • The Show serial monitor menu item is replaced by Command Palette Particle: Serial Monitor.
  • The Show cloud variables and Show cloud functions menu items do not have a direct replacement but the Command Palette Particle: Launch CLI and using the particle list CLI command does return the same information (for all of your devices).

Particle Dev Status Bar

In the bottom status bar:

  • The device selector is replaced by the Command Palette Particle: Configure Workspace for Device.
  • The other status bar information is displayed on the VS Code status bar. If the status bar is not visible, you can change that using Command Palette View: Toggle Status Bar Visibility.

If you are used to the editing keyboard shortcuts, you can install the Atom keymap. Open the Command Palette and select Preferences: Keymaps.

Learn More

Additional questions and answers are in the FAQ.