Schedule a Firmware Upgrade

POST /campaigns/firmware/{acc}

Schedules a firmware upgrade for devices.

Uses and Requirements

This API allows you to schedule a firmware upgrade for devices. The response includes an upgrade ID that is included in all callback notifications about the status of the upgrade 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.

If you have registered a callback URL, ThingSpace sends 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/v3/campaigns/firmware/{acc}

Resource Path Parameters

Parameter Name Data Type Description
acc
required		 string The billing name of the account. An account name is usually numeric, and must include any leading zeros.

Header Parameters

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

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.

Parameter Name Data Type Description
campaignName string The campaign name.
firmwareName
required		 string The name of the firmware you are upgrading to.
firmwareFrom
required		 string The name of the old firmware on the device.
firmwareTo
required		 string The name of the new firmware you are upgrading to.
protocol
required		 string Valid values include:
  • LWM2M
  • OMA
  • HTTP
startDate
required		 string($date) Campaign start date.
endDate
required		 string($date) Campaign end date.
campaignTimeWindowList Array  

   startTime
   required

 integer Start hour in range [0-23], current hour >= startTime. When the current hour falls between the startTime and the endTime, the campaign starts.
   endTime
   required		 integer End hour in range [1-24], current hour < endTime. The endTime must be at least 4 hours after the startTime.
deviceList
required		 array of deviceID objects Device IMEI list.

Example Request

Request a firmware upgrade.

{
  "campaignName": "Smart FOTA - test 4",
  "firmwareName": "SEQUANSCommunications_GM01Q_SR1.2.0.0-10512_SR1.2.0.0-10657",
  "firmwareFrom": "SR1.2.0.0-10512",
  "firmwareTo": "SR1.2.0.0-10657",
  "protocol": "LWM2M",
  "startDate": "2021-09-29",
  "endDate": "2021-10-01",
  "campaignTimeWindowList": [
    {
      "startTime": 18,
      "endTime": 22
    }
  ],
  "deviceList": [
    "15-digit IMEI"
  ]
}

Success Responses

Status 200

Parameter Name Data Type Description
id string The campaign identifier.
accountName string The ThingSpace billing account number
campaignName string The campaign name.
firmwareName string The name of the firmware to which you are upgrading.
protocol string Valid values include:
  • LWM2M
  • OMA
  • HTTP
make string FOTA make of the device.
model string FOTA model of the device.
firmwareFrom string The name of the old firmware on the device.
firmwareTo string The name of the new firmware to which you are upgrading.
status string Campaign level status.
startDate string($date) Campaign start date.
endDate string($date) Campaign end date.
campaignTimeWindowList Array  
   startTime integer Start hour in range [0-23], current hour >= startTime.
   endTime integer End hour in range [1-24], current hour < endTime. The endTime must be at least 4 hours after the startTime.

Example Success Response

Status 200

{
    "id": "f858b8c4-2153-11ec-8c44-aeb16d1aa652",
    "accountName": "0000123456-00001",
    "campaignName": "Smart FOTA - test 4",
    "firmwareName": "SEQUANSCommunications_GM01Q_SR1.2.0.0-10512_SR1.2.0.0-10657",
    "protocol": "LWM2M",
    "firmwareFrom": "SR1.2.0.0-10512",
    "firmwareTo": "SR1.2.0.0-10657",
    "make": "SEQUANS Communications",
    "model": "GM01Q",
    "status": "CampaignRequestPending",
    "startDate": "2021-09-29",
    "endDate": "2021-10-01",
    "campaignTimeWindowList": [
        {
            "startTime": 18,
            "endTime": 22
        }
    ]
}

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.