Introduction to the Software Management Services API

ThingSpace Software Management APIs allow customers to perform over-the-air firmware upgrades while devices are in the field. This service allows compatible 4G or 5G devices to leverage standards-based Open Mobile Alliance Device Management (OMA-DM)  or Lightweight Machine to Machine (LWM2M) device management protocols to bootstrap the device, check its firmware version, and upgrade it accordingly. If your device was certified via the Verizon Open Development program after January 2019, it should automatically work with the ThingSpace Software Management  API.  

Since September 2020, the Open Development program has also started offering optional software management using HTTP(S).  If you are unsure of the certification status or experience any problems using your device with this service, please reach out to us at VZW.FOTA-Services@VerizonWireless.com and we can work with you to help ensure a seamless experience.

Software Management Requirements

ThingSpace Software Management APIs requires:

  • Compatible 4G/5G OMA-DM, LWM2M devices or devices using the Verizon HTTP-based software management client.  Open Development Showcase can be used for a cursory compatibility check because devices are marked with “Verizon FoTA solution,” but please check with Open Development VZW.FOTA-Services@VerizonWireless.com if you are uncertain.

  • An understanding of whether your devices are OMA-DM, LWM2M, or HTTP-based

  • Your Verizon Enterprise billing account number

  • Your ThingSpace Develop account credentials

  • Your account’s UWS login credentials

Using Software Management Services API also requires:

  • Licenses to be acquired and assigned to devices

  • The compatible devices should be bootstrapped to their respective firmware/software management server and reporting make, model, and running firmware/software version.

  • A new firmware/software package to be available that matches the make, model, and running firmware/software version of the eligible devices. The device OEM needs to certify the package with Open Development and make it available on ThingSpace once published.

    If you believe the package is available but not showing on your account, please contact Open Development VZW.FOTA-Services@VerizonWireless.com. The Open Development certification process is introduced here.

The Over-the-Air Software Upgrade Process

Depending on the device implementation and the update, the software delivered could be considered a baseband module update, or an application update to the host device, and could be classified as “firmware” or “software.” The terms may be used interchangeably, but baseband software is almost always considered firmware and is typically delivered with Open Mobile Alliance Device Management (OMA-DM)  or Lightweight Machine to Machine (LWM2M) protocols.  Delivering any types of these software upgrades to IoT devices over the wireless network is generally referred to as “Firmware-over-the-air” (FOTA).  

The  process of a Firmware-over-the-Air upgrade:

Pre-requisites:

  1. A Verizon customer contacts their Verizon account representative to subscribe to ThingSpace Software Management Services.

  2. The customer assigns Software Management Services licenses to eligible devices.
  3. A device manufacturer certifies a software package and Open Development uploads a new firmware/software version to ThingSpace. The software package is stored in ThingSpace with a particular make, model and starting firmware/software version prerequisite (from version), along with its new target version (to version).

Upgrade Process


The Firmware-over-the-Air upgrade process is described in detail here, and illustrated in the following diagram.

  1. ThingSpace sends a callback message to notify ThingSpace Software Management users about the new firmware/software. Alternatively, the OEM can notify the users directly.

  2. Users schedule a firmware/software upgrade campaign for a list of eligible devices.

  3. During the campaign timeframe, ThingSpace instructs the devices to fetch the new firmware/software via either a push notification or a pull/check-in. 

  4. The devices acknowledge they must upgrade the firmware/software and request the update. A callback message is sent to notify the user of the upgrade status.

  5. After the firmware/software has been installed, the device reports its current version to ThingSpace, and ThingSpace sends another callback message to notify the customer that the upgrade has ended. 

After the upgrade, users can view a report to see the list of upgraded devices and any device upgrades that were not successful.

API Versions:  /v1,  /v2, and /v3

The system stack is dependent upon the device client compatibility: 

  • If the devices are using the the OMA-DM protocol, the campaigns are “pushed” based on the user-designated start day and are accessed via the /v1 APIs. 

    Note: Use V3 API’s to manage licenses, they are backwards compatible

  • If the devices are certified with the Verizon HTTP FOTA client, they use a “pull”-based system and are accessed via a different set of APIs via the /v2 APIs. The “pull”-based system has a campaign start time that is dependent on: 

The user-designated start and end-date and optional time windows.

  • How often the devices check-in inside the desired campaign windows.

    Note: Use V3 API’s to manage licenses, they are backwards compatible

  • If devices are LWM2M, users can manage these campaigns via the /v1 or the /v3 APIs; both methods are “push”-based.

    • Using the /v1 APIs, campaigns are “pushed” to all devices on the user-designated start date.

    • Using the /v3 APIs, campaigns are “pushed” to cohorts of devices within a defined date window (and optional time window), considering network context of the devices.

    • It is recommended to use the V3 API’s for LWM2M campaigns but the V1 version is still supported. 

Receiving upgrade information in callbacks

The ThingSpace Software Management Services API can send callback messages when new firmware versions are available and when upgrades start and finish. The messages will be REST messages POSTed to a registered URL. You are responsible for creating and running a listening process on your server at that URL to receive and parse the messages.

See About Callback Services for more information.

To get started

You can follow these general steps to get started with the Software Management Services API:

  1. Read the documentation to understand what capabilities are available in the API and which devices are eligible.
  2. Contact your Verizon account representative to purchase a subscription for the ThingSpace Software Management Services. If you are a new customer, contact iotdeveloper@verizon.com to find out how to get started.
  3. Register on the ThingSpace Develop site to get access to the API.
  4. Verify that you have UWS credentials to obtain session tokens.
  5. Create a simple callback listener to be ready to receive messages from ThingSpace.
  6. Start coding your application.