Schedule Firmware Upgrade

Schedule a Firmware Upgrade:
POST /upgrades

Schedules a firmware upgrade for devices. The response includes an upgrade ID that will be included in all callback notifications about the status of the upgrade, and that you can use to check the status of the upgrade or cancel it.

Note: A synchronous response with no errors means that the request has been accepted, but does not mean that the upgrade has been scheduled. You will receive an “upgradeScheduled” callback message when the upgrade is actually scheduled, and you can check the status of the upgrade to see when it changes from “RequestPending” to “Queued,” which means that the upgrade has been scheduled.

Contents

See also:
Get information about an upgrade
Get upgrades by status
Modify a scheduled upgrade
Get a list of firmware for an account
Cancel a scheduled upgrade

Uses and Requirements

After you send a request to schedule an upgrade, the upgrade advances through several states:

  • RequestPending: The upgrade request has been accepted but is not scheduled yet.
  • Queued: The upgrade is scheduled, but has not started.
  • InProgress: The upgrade is in progress.
  • Finished: The upgrade has finished for all devices in the request.

Additionally, if a “RequestPending” upgrade cannot be scheduled, the status will become “RequestFailed,” and if a “Queued” upgrade does not run when scheduled the status will become “UpgradeFailed.” If you have registered a callback URL, ThingSpace will send callback notification messages each time the status of an upgrade changes.

If your account has only a monthly recurring charge (MRC) subscription for the Software Management Services, you must assign a license to each device that you want to upgrade before you can schedule an upgrade for those devices.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/fota/v1/upgrades

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization token and a current VZ-M2M session token, and must set the Content-Type to JSON.

Parameter Name Data Type Description
Authorization
required
string HTTP Authorization request header containing a valid Bearer token.
VZ-M2M-Token
required
string A valid session token returned by a Connectivity Management POST /session/login request.
Content-Type
required
string Must be application/json.

Request Body

The request body identifies the devices that you want to upgrade, the firmware image that you want to apply, and the date that you would like the upgrade to start.

Parameter Name Data Type Description
accountName
required
string The name (number) of the billing account.
firmwareName
required
string The name of the firmware image, from a GET /firmware response.
startDate
required
date string The date that you would like the upgrade to begin.
deviceList
required
array of IMEI strings The IMEIs of the devices to upgrade. All of the devices must be of the same make and model, and must be at the same firmware version.

Example Request

Schedule firmware upgrades for two devices:

curl https://thingspace.verizon.com/api/fota/v1/upgrades -H 'Authorization: Bearer $AUTH_TOKEN' -H 'VZ-M2M-Token: $M2M_TOKEN' -H 'Content-Type: application/json' -d 
{
  "accountName": "0402196254-00001", 
  "firmwareName": "FOTA_Verizon_Model-A_01To02_HF", 
  "startDate": "2018-04-01",
  "devicelist": [
    "990003425730535", 
    "990000473475989"
  ]
}

Success Responses

Status 2xx

A successful request returns information about the scheduled upgrade and an upgrade ID that you can use to check the status of the upgrade or cancel it if needed:

Parameter Name Data Type Description
id UUID string The unique identifier for this upgrade. Save this ID so that you can check on the status of the upgrade.
accountName string The name (number) of the billing account.
firmwareName string The name of the firmware image that will be used for the upgrade.
firmwareTo string The name of the firmware version that will be on the devices after a successful upgrade.
startDate string The intended start date for the upgrade.
status string The current status of the upgrade, which will always be “RequestPending” for new upgrade requests.
deviceList array of objects A JSON object for each device that will be upgraded, showing the device IMEI and “RequestPending” status.

Example Success Response

{
  "id": "e3a8d88a-04c6-4ef3-b039-89b62f91e962",
  "accountName": "0242078689-00001",
  "firmwareName": "FOTA_Verizon_Model-A_01To02_HF",
  "firmwareTo": "VerizonFirmwareVersion-02",
  "startDate": "2018-03-05",
  "status": "RequestPending",
  "deviceList": [
      {
          "deviceId": "990003425730535",
          "status": "RequestPending"
      },
      {
          "deviceId": "990000473475989",
          "status": "RequestPending"
      }
  ]
}

Failure Responses

Status 400

All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.