Versions and upgrades

Introduction

Most applications consist of two parts: Device OS ("system firmware") and the user application ("user firmware"). Device OS contains the code necessary to communicate with the hardware on the device (including cellular or Wi-Fi radios), as well as the Particle cloud. The user firmware is the part specific to your product or application and is typically the code you've written in C/C++.

Separating the two makes upgrading the smaller user firmware quick and easy allowing for rapid test and debug cycles, even when programming firmware over cellular networks.

Unlike desktop and laptop computers, Particle devices only run a single user application at a time. Programing new user firmware replaces the previous user firmware.

Each user firmware binary specifies the minimum version of Device OS that it is compatible with, referred to as the target version. For example, if your user firmware targets 1.5.0, it will work not only on 1.5.0, but also 1.5.2, and 2.0.0.

If you flash user firmware that requires a newer version of Device OS than is currently installed on the device, the device will automatically upgrade. For example, if the device has 1.5.2 and you target your user firmware for 2.0.0, the user firmware would not initially be able to run because the Device OS version is too old. However, at boot, the device will discover this and go into safe mode (breathing magenta), and the cloud will send down the missing binaries. This normally requires a few reboot cycles that happen automatically.

Unlike computer operating systems like Windows or Mac, Device OS will never be automatically updated under your application. You must manually opt into each update, and updates are generally not required. Because of the more limited function set and smaller attack surface, recommended updates for security reasons are rare.

Version upgrade flow

For products, you will typically upgrade Device OS using these steps:

By targeting a new version of Device OS in your product firmware it will assure that devices will be upgraded as necessary.

Version numbering

Device OS releases follow semantic versioning ("semver") guidelines with MAJOR.MINOR.PATCH numbering. For example in the 1.5.x release line, there are 1.5.0, 1.5.1, and 1.5.2 versions.

There are also occasionally beta releases (2.0.0-beta.1) and more commonly release candidate ("rc") releases (2.0.0-rc.1). There may be multiple release candidates (for example, 2.0.0-rc.4) before a final release is made (2.0.0).

A list of valid version numbers can be found in the release notes.

LTS Versions

Particle is constantly improving Device OS with new releases that add new features, increase performance, and improve the standard behavior of Particle devices to better meet the needs of our customers. However, for some customers, constant ongoing development and changes in behavior can create undesired risk to the stability and reliability of existing applications.

Many enterprises building and deploying mission-critical solutions with Particle value reliability over everything else. For those customers, Particle develops and releases Long Term Support (LTS) releases of Device OS that deliver consistent behavior and stable performance for device applications over extended periods of time.

Long Term Support (LTS) releases for Device OS are independent branches of Device OS that are feature-frozen in time. They do not receive updates with new features, API changes, or improvements that change the function or standard behavior of the device.

LTS releases are, however, supported by an extended support window which address critical bugs, regressions, security vulnerabilities, and issues that affect our wider enterprise customer community.

LTS release lines have even major version numbers (2.0.x, 4.0.x, etc.). After 2.0.0 is released, new feature development will occur in the 3.x.x release line with only important bug and security fixes back-ported to 2.x.x.

Platform Models Previous LTS Test With Current LTS Minimum Version
B-Series SoM B404X 4.2.0 4.2.0 4.0.02
B-Series SoM B404 2.3.1 4.2.0 4.2.0 2.3.01
B-Series SoM B402, B524, B523 2.3.1 4.2.0 4.2.0
Boron BRN404X 4.2.0 4.2.0 4.0.02
Boron BRN404, BRN402, BRN314, BRN310 2.3.1 4.2.0 4.2.0
Argon 2.3.1 4.2.0 4.2.0
E404X E404X 4.2.0 4.2.0 4.0.02
Tracker T404, T524, T523 ONE404, ONE402, ONE524, ONE523 3.3.1 4.2.0 4.2.0
  • 1B404 SoMs should only use Device OS 2.3.0 or later. While older units worked with older versions, newer units from the factory will only with with 2.3.0 and later due to a required component change. It's recommended that all B404 units use this version for compatibility.
  • 2B404X, BRN404X, E404X, and Tracker X devices require Device OS 4.0.0 or later. The most recent 4.x release, currently 4.2.0.

Devices that must stay on 2.x LTS

Platform Models Current LTS Minimum Version
E-Series E404, E402, E314, E313, E310 2.3.1 2.2.01
Electron ELC402, U260, U270, G350 2.3.1 2.2.01
P1 2.3.1 1.2.12
Photon 2.3.1 1.2.12

-1The most recent versions of the devices shipped from the factory with 2.2.0. This device can use older versions of Device OS but we do not recommend downgrading the Device OS whenever possible. -2The Photon and P1 shipped with 1.2.1 from the factory. This device can use older versions of Device OS but we do not recommend downgrading the Device OS whenever possible.

Devices that cannot use LTS yet

Platform Current Version Minimum Version
P2 5.8.0 5.0.01

1Some devices from the factory shipped with 3.2.1-p2.3. This version should not be used in production, using the latest 5.0 release, currently 5.8.0, is recommended.

Using pre-release versions

Particle recommends using the latest LTS versions compatible with your device, except in the following cases:

  • New hardware may require using the developer preview (3.x, 5.x, ...) release line until the next LTS release.
  • Testing

We recommend testing your firmware on new releases to assure compatibility, even if you decide not to release that version to your entire fleet.

Not every release will have a release candidate (rc), but if it does, this is a good opportunity to test your code for compatibility.

Because it is very difficult to downgrade Device OS, we recommend testing candidates on devices that you have easy physical access to so you can downgrade by USB if necessary. Deploying on non-critical test devices where it is OK if the device is not fully functional until appropriate fixes are made is also a good alternative. Once the final release version of a rc version is released we recommend moving all devices off the rc version.

Upgrading Device OS

OTA (over-the-air)

In general, flashing a version of your user firmware will automatically update the version of Device OS automatically over-the-air when necessary. Note this will only ever upgrade. If you have Device OS 2.0.0 on your device and flash user firmware targeting 1.5.2 Device OS will not be downgraded! However, your firmware should still run because the target version is the minimum compatible version.

particle update (USB)

Using the Particle CLI allows upgrading to the current default release over USB. This is a common option because it's generally faster than OTA, and does not use your cellular data allowance.

  • Issue the update command from a Command Prompt or Terminal window:
particle update

This will update the the latest LTS supported by the device, except in the case that the device does not yet an LTS version yet, in which case it will be the latest developer preview release.

Additionally, you can upgrade to a specific version of Device OS using the --target option. This is handy for moving to the developer preview line of releases instead of LTS.

$ particle update --target 5.5.0

You can also downgrade Device OS, however:

  • In general we recommend that you do not downgrade Device OS on devices, except to roll back from developer preview back to the adjacent LTS version.
  • If you are downgrading, you should first downgrade user firmware or using particle flash --local tinker as user firmware that targets a newer version of Device OS will cause it to update back to its original version OTA after reconnecting to the cloud.

Boron LTE BRN402 and B-Series SoM B402

If you are downgrading a Boron LTE (BRN402) or B-Series SoM B402 from Device OS 2.0.0 or later, to 1.5.1 or earlier, you must first install 1.5.2, allow the device to boot and connect to cellular before downgrading again to an earlier version. The reason is that 2.0.0 and later use a higher baud rate for the cellular modem, and on the SARA-R410M only, this setting is persistent. Older versions of Device OS assume the modem is using the default of 115200 and will fail to communicate with the modem since it will be using 460800. Device OS 1.5.2 uses 115200, however it knows it can be 460800 and will try resetting the baud rate if it can't communicate with the modem.

Browser DFU

Certain browsers can do a DFU upgrade or downgrade right from the browser page with no software or app install. See Device Restore USB for more information.

  • There is limited browser support on desktop: Chrome, Opera, and Edge. It does not work with Firefox or Safari. Chrome is recommended.
  • It should work on Chromebook, Mac, Linux, and Windows 10 on supported browsers.
  • It should work on some Android phones that support USB OTG when using Chrome, Opera, or Samsung Internet browsers.

Manually over USB

It is also possible to update manually over USB. This allows for upgrades as well as downgrades, and operation while offline. This is rarely needed as particle update --target x.y.z is far easier.

Show manual steps

Manually over SWD/JTAG

On production lines, it's common to update devices using SWD/JTAG. This can be done with:

Device Gen 2 Gen 3 Windows Linux Mac Notes
ST-LINK/v2       Using ST/LINK for Windows
ST-LINK Mini   Using openocd
Particle Debugger Using openocd
Segger J-LINK

You can use device restore images to restore a device to a known state using a SWD/JTAG debugger. This works for both upgrades and downgrades and is by far the fastest way to do this.

A hex file generator is available to take a device restore hex file and replace Tinker (or Tracker Edge) with your custom user firmware binary. This can make it very easy to mass-produce devices with exactly the version of Device OS and your firmware you want.

Additional information can be found in the JTAG and SWD Guide.

Using Particle Workbench

In Particle Workbench you can also choose to upgrade or downgrade Device OS when flashing code.

  • Select the version of Device OS from the command palette using Particle: Configure Project for Device.
  • Use Particle: Flash application and Device OS (local)

There are several caveats to this, however:

  • Workbench will not upgrade the bootloader. Your device may go into safe mode and require a connection to the cloud to update it, or you can do so over USB.
  • Workbench will not downgrade the bootloader. This generally will function, but the farther back you go in versions the more likely this is to not work. Downgrading the bootloader by USB is recommended as bootloader downgrades are never done by the cloud.
  • Workbench will not upgrade or downgrade the SoftDevice on Gen 3 platforms. This is not always required, but if it is you'll need to do so OTA or by USB.
  • Workbench will not upgrade or downgrade the Argon or Tracker SoM NCP, though this is almost never required.

NCP Upgrade

The Argon and Tracker have a Network Coprocessor (NCP). This rarely needs to be updated manually, as it will be upgraded OTA if necessary. There is currently no scenario in which it would need to be downgraded.

For more information see Argon and Tracker NCP.

Less common scenarios

There are a few less common upgrade scenarios described in the section below. Use the disclosure triangle to view.

Less common scenarios

Downgrading Device OS

While upgrades to Device OS are automatically handled by Safe Mode (breathing magenta), downgrades are not handled automatically.

USB Downgrade - Browser

Certain browsers can do a DFU upgrade or downgrade right from the browser page with no software or app install. See Device Restore USB for more information.

  • There is limited browser support on desktop: Chrome, Opera, and Edge. It does not work with Firefox or Safari. Chrome is recommended.
  • It should work on Chromebook, Mac, Linux, and Windows 10 on supported browsers.
  • It should work on some Android phones that support USB OTG when using Chrome, Opera, or Samsung Internet browsers.

USB Downgrade - Particle CLI

You can downgrade USB in DFU mode (blinking yellow). This can generally be done in one version jump, with the following exception:

Boron LTE BRN402 and B-Series SoM B402

If you are downgrading a Boron LTE (BRN402) or B-Series SoM B402 from Device OS 2.0.0 or later, to 1.5.1 or earlier, you must first install 1.5.2, allow the device to boot and connect to cellular before downgrading again to an earlier version. The reason is that 2.0.0 and later use a higher baud rate for the cellular modem, and on the SARA-R410M only, this setting is persistent. Older versions of Device OS assume the modem is using the default of 115200 and will fail to communicate with the modem since it will be using 460800. Device OS 1.5.2 uses 115200, however it knows it can be 460800 and will try resetting the baud rate if it can't communicate with the modem.

Use the particle update --target x.y.z option to specify the version to downgrade to.

Show manual steps

OTA - Downgrade

The downgrade process is generally the reverse of the upgrade process, however when downgrading OTA, there may be additional intermediate steps you need to make.

  • Downgrade the user firmware, if necessary. Make sure your user firmware targets the version you are intended to downgrade to, or an earlier version, otherwise safe mode healer will kick in and upgrade the device while you are trying to downgrade!

  • Note the required intermediate downgrades. This is important! If you skip this step, the device will become unreachable and will require downgrade by USB.

Device Version Version Version Version
Electron/E-Series 1.2.1 0.7.0 0.6.4 0.5.5
Photon, P1 1.2.1 0.7.0 0.6.4 0.5.5
Boron LTE, B-Series SoM B402 1.5.2

For example: Say you have an Electron running 1.5.2 and you want to downgrade it to 0.6.2 OTA. We don't actually recommend doing that, but if for some reason you had to, you would first need to downgrade to 1.2.1. Once that was completed, you would downgrade to 0.7.0. Then 0.6.4. Then finally 0.6.2, your desired target.

  • For each required Device OS downgrade, download the binaries from the Device OS releases page.

  • Flash the system parts in reverse order. Wait not only for the command to complete, but also for the device to come back online again. Using the Events page in the console can be helpful for this.

Example: Downgrade Electron OTA

For example, say you want to downgrade device named "electron7" from 2.0.0 to 1.5.2 OTA:

  • Flash your application targeting the older version of Device OS, or Tinker:
# Downgrade user firmware
particle flash electron7 tinker
  • Flash system parts in reverse numerical order. This is generally 3, 2, 1 for the Electron and E-Series. 2, 1 for Photon and P1. For Gen 3 devices, there is only 1 system part.
# Flash system parts in reverse order
particle flash electron7 electron-system-part3@1.5.2.bin

# Wait until spark/status online event is received
particle flash electron7 electron-system-part2@1.5.2.bin

# Wait until spark/status online event is received
particle flash electron7 electron-system-part1@1.5.2.bin

After each part, wait for the device to come back online. This is shown in the Events page in the console.

Online event

  • Flash the bootloader.
particle flash electron7 electron-bootloader@1.5.2+lto.bin
  • For Gen 3 devices, you may need to flash the SoftDevice.

  • Your device should now be online and successfully downgraded.

SWD/JTAG device restore

Using a SWD/JTAG debugger such as the Particle Debugger, ST-LINK, or Segger J-Link, plus device restore images make it restore a device to a known state or downgrade Device OS easily.

With some combinations of browsers, an upgraded Particle Debugger, and a Gen 3 device, you can also do a JTAG Device Restore with no software or app install required.