What’s new in the Software Management Services API

07/15/22 - Version 3.1 

Network-aware Software Management for OMA-DM Devices

Previously, any OMA-DM campaign included only one FOTA upgrade attempt. For example, an OMA-DM campaign may begin at 12:00 AM UTC which is when the device(s) are notified. This request is queued in the network for 4 hours and if the device was powered off during that window, the campaign would be considered a failure. And a new campaign would need to be created.

This feature introduced a network-aware campaign experience specific for OMA-DM. Now, after that 4 hour window fails, ThingSpace and the Verizon network will queue this device in the network indefinitely for an upgrade. The next time it powers on, it will be notified for upgrade and the campaign will begin. If that campaign fails, it will be queued up again indefinitely. See the campaign timing documentation for more detail. This new behavior has implications on the device firmware history API and get information about an upgrade API. 

08/25/21 - Version 3.0 

Network-aware Software Management for LWM2M Devices

The existing product feature set included managing software/firmware for devices certified for Verizon FOTA using OMA-DM, LWM2M, and HTTP protocols. This release introduces many new capabilities for LWM2M devices when using the new /v3 API. Existing behavior has not changed for the /v1 and /v2 APIs.

The new /v3 APIs for LWM2M devices includes these new features:

  • Scheduling campaigns with LWM2M now requires a start and end date. Adding an endDate parameter gives ThingSpace an opportunity to coordinate the updates based on network context and affords additional time to manage re-tries when updates fail.  If the campaign is too large and the date or time windows are too narrow, devices may not be upgraded. Users are encouraged to create large windows if possible, up to one month.
  • Scheduling campaigns with LWM2M now allows optional time-windows. Users with business requirements that specificy what times are, and are not acceptable for firmware upgrades can use this parameter. Some examples of when you might use this feature:
    • Smart Light - You may not want to updated at night.
    • School bus camera - You may not want to upgrade during the morning and afternoon.
    • Vending machine - You should upgrade at night when people are not around.
  • ThingSpace is now aware of the specific cell the devices are connected to when scheduling campaigns. In cases where a cluster of devices in a campaign are within the same cell, ThingSpace splits the campaign into multiple smaller campaigns to minimize failures and to help increase the success rate and delivery time. Managing these smaller campaigns is transparent to users. The status is reflected in the campaign report API.
  • The campaign reports API has been enhanced significantly:
    • In v1, the device status was updated daily. In v3, users should notice much more up-to-date information as the campaign progresses, including incremental updates within a given day. A timestamp is now included to indicate when that status changed.
    • New result reasons have been added to aid in understanding unexpected results of this device in the campaign. For example, in v1 a failure may read “Firmware update failed to device” but in v3 the result could show “The network reports the device is not reachable.”
    • A recentAttemptTime parameter is introduced to understand when the device was requested to initiate a LWM2M firmware update. A recent attempt could be associated with a success or a failure.
    • A nextAttempTime gives insight to when this device will be requested to be upgraded. The attempt could be the initial attempt or a retry after a failure.
    • With large campaigns clustered in cells, devices may show as queued or scheduled for a future uncertain date, while other devices in this campaign are processed.
  • Pilot campaigns are now mandatory for LWM2M devices using the /v3 APIs. Similar to V2, pilot campaigns ensure users run small scale tests before larger ones. The time between when a user schedules a pilot campaign for “today” and when the FOTA operation is initiated on the devices is significantly shorter with small campaigns.
  • The /v3 JSON model was changed to more closely match the /v2 APIs.

02/24/21 - Version 2.39

New and Updated Resources

  • Three new /v2 requests to add or remove devices from a cancellation list when subscriptions changes to a lower number of devices.
    • POST /licenses/{account}/cancel
    • DELETE /licenses/{account}/cancel
    • GET /licenses/{account}/cancel
  • Three new /v2 requests to upload, update, and get a list of configuration files that can be campaigned to compatible devices.
    • GET /files/{account}
    • POST /files/{account}
    • PUT /files/{account}
  • A new v2 request to schedule a campaign for configuration files. Configuration files are monitored and modified by using the existing /v2 campaign APIs.
    • POST /campaigns/files/{account}

    • 09/30/20 - Version 2.33

    HTTP Software Management

    The existing product feature set was based on managing software/firmware for compatible OMA-DM and LWM2M devices using Firmware-over-the-Air (FOTA) technology. When LWM2M or OMA-DM campaigns begin, the respective service sends a message to the device and instructs it to fetch the new firmware update (push-based). Those capabilities still exist and are accessible via the /v1 set of APIs.

    This release introduces an entirely new system and stack for managing software/firmware on compatible devices. The new system and stack is dependent on device-client compatibility:

    • If the devices are certified with a Verizon HTTP(S) FOTA client, they use a new system and access a new and different set of APIs via a /v2 reference path.
    • If the devices are LWM2M or OMA-DM devices, the features and APIs have not changed.

    The new APIs are very familiar but have some different features. One notable difference with the new system is that the campaign time is dependent 1) on when the campaign windows are set and 2) how often the devices check-in (pull-based) inside the desired campaign windows.

    New Resources

    The following /v2 APIs are now available for devices using HTTP-based FOTA. They are similar to the existing OMA-DM- and LWM2M-based FOTA, but you should review the API Reference to understand the nuances, particularly the change in the endpoint URIs.

    • Subscriptions
      • Retrieves the number of FOTA subscriptions for HTTP devices by account
        • GET /subscriptions/{acc}
    • Licenses
      • Returns information about an account’s Software Management Services licenses and a list of licensed devices.
        • GET /licenses/{acc}
      • Assign FOTA licenses to devices
        • POST /licenses/{acc}/assign
      • Remove FOTA licenses from devices
        • POST /licenses/{acc}/remove
    • Campaigns
      • Schedule a software upgrade for HTTP devices.
        • POST /campaigns/{acc}
      • Get information about a specified upgrade, including the target date of the upgrade and the status of the upgrade for each HTTP device
        • GET /campaigns/{acc}/{campaignId}
      • Cancel a software upgrade
        • DELETE /campaigns/{acc}/{campaignId}
      • Add or remove devices from a software upgrade
        • PUT /campaigns/{acc}/{campaignId}
      • Change campaign dates and time windows
        • PUT /campaigns/{acc}/{camapignId}/dates
    • Callbacks
      • Create https callback address
        • POST /callbacks/{acc}
      • Update callback address
        • PUT /callbacks/{acc}
      • Get list of registered callback listeners
        • GET /callbacks/{acc}
      • Delete the callback
        • DELETE /callbacks/{acc}
    • Available software
      • Get list of available software
        • GET /software/{acc}
    • Devices
      • Get a list of devices in an account
        • GET /devices/{acc}
    • Reports
      • Get device software upgrade history
        • GET /reports/{acc}/devices/{deviceId}
      • Get campaign history for specified status
        • GET /reports/{acc}/campaigns
      • Get a campaign device status
        • GET /reports/{acc}/campaigns/{campaignId}/devices
    • Verbose Logging
      • Get a list of devices with logging enabled
        • GET /logging/{acc}/devices
      • Enable logging for a list of DeviceStatus
        • PUT /logging/{acc}/devices
      • Disable logging for a list of DeviceStatus
        • DELETE /logging/{acc}/devices
      • Enable logging for a specific device
        • PUT /logging/{acc}/devices/{deviceId}
      • Disable logging for a specific devices
        • DELETE /logging/{acc}/devices/{deviceId}
      • Get logs for a specific devices
        • GET /logging/{acc}/devices/{deviceId}/logs
      • Get check-in history for a specific device
        • GET /logging/{acc}/devices/{deviceId}/checkInHistory

     

    10/30/18 - Version 2.10

    New and Updated Resources

    • GET /devices/{account}
      • Now accepts an optional clientType query string to only return devices of the specified client type (device management protocol).
      • Includes the client type of each device in the response.
    • GET /firmware/{account}
      • Now accepts an optional clientType query string to only return firmware that is applicable to the specified client type (device management protocol).
      • Includes the applicable client type for each firmware included in the response.

    10/3/18 - Version 2.9

    New and Updated Resources

    • The username and password parameters have been removed from callback messages, and are no longer valid when registering a callback listener:
      • POST /callbacks/{account}
    • The Get Device List reponse now includes that status of each device’s line of service, such as “active” or “suspend.”
      • GET /devices/{account}

    9/4/18 - Version 2.7

    New and Updated Resources

    • A new request to add or remove devices from a scheduled upgrade campaign:
      • PUT /upgrades/{account}/upgrade/{upgradeId}

    6/28/18 - Version 2.4.1

    New and Updated Resources

    • These three requests now return {"success": true} for successful completion:
      • DELETE /licenses/{account}/cancel
      • DELETE /callbacks/{account}/name/{service}
      • DELETE /upgrades/{account}/upgrade/{upgradeId}

    4/18/18 - Version 2.2

    New and Updated Resources

    • DELETE /licenses/{account}/cancel Deletes the entire list of cancellation candidate devices.

    03/22/2018

    Initial release

    Initial release of the ThingSpace Software Management Services API.