Firmware Upgrade API


Note
This API only applies to mesh devices.

Note
Firmware upgrades are only supported on Cisco IOS.

This chapter describes the Firmware Upgrade API.

Using the Firmware Upgrade API

In your IoT FND NB API client application, use this IoT FND server URL to access the Firmware Upgrade API WSDL:

http://<server_address> /nbapi/meshDeviceOps?wsdl

Firmware Upgrade API Method Calls

The following are the Firmware Upgrade API method calls:

The Firmware Upgrade API module allows client applications to start and stop firmware uploads to a group of mesh devices, check their firmware upload status, obtain firmware information by firmware group, setup a backup firmware image, and schedule a firmware reload.

Specified input parameters are not case sensitive, and are validated before further processing by IoT FND. All input parameters are character string. The utcDateAndTime format is “YYYY-MM-DD*HH:MM:SS.” The following table lists return codes sent by the Firmware Upgrade module.

Table 1. Firmware Upgrade API Return Codes

Code

Definition

0

Success.

–1

Unsupported device type.

–2

Firmware group not found.

–3

Firmware image not found.

–4

Invalid date and time format (scheduleReload).

–5

Invalid firmware image.

–6

Cannot perform operation; firmware group is active.

–7

Cannot find a device in the up state in the firmware group.

–8

Cannot perform operation; empty firmware group.

–9

Cannot stop firmware update on inactive firmware group.

–10

Invalid load date specified.

–11

Simultaneous firmware group operations over maximum threshold.

–12

Cannot perform operation; firmware group file image only present on the nodes.

–99

Indicates a lower-layers system error, including:

  • System busy

  • Invalid user permissions (Role Based Access Control)

  • Another operation is pending for the group

A text message returns with the return code.

startUpload

This call initiates the firmware upgrade on the specified firmware group with the specified firmware image.

Prototype


startUpload (devType, firmwareGroup, firmwareImageName)

Parameters

The following table describes the parameters in the interface.

Table 2. startUpload Parameters

Parameter

Options

Description

devType

cgmesh

The device to receive the firmware upgrade.

firmwareGroup

string

The firmware group of devices to receive the firmware upgrade.

firmwareImageName

string

The firmware image name.

Results

The following table describes the parameters in the response.

Table 3. startUpload Results

Value

Description

0

Success.

-1

devType not found or is not supported.

-2

firmwareGroup not found or is invalid.

-3

firmwareImageName not found or is invalid.

-99

System error.

SOAP XML Request Format


startUpload
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <mes:startUpload>
         <firmwareGroup>?</firmwareGroup>
         <firmwareImageName>?</firmwareImageName>
      </mes:startUpload>
   </soapenv:Body>
</soapenv:Envelope>

stopUpload

This call stops the firmware upgrade in progress on the specified firmware group.

Prototype


stopUpload (devType, firmwareGroup)

Parameters

The following table describes the parameters in the interface.

Table 4. stopUpload Parameters

Parameter

Options

Description

devType

cgmesh

The device to receive the firmware upgrade.

firmwareGroup

string

The firmware group of devices to receive the firmware upgrade.

Results

The following table describes the parameters in the response.

Table 5. stopUpload Results

Value

Description

0

Success.

-1

devType not found or is not supported.

-2

firmwareGroup not found or is invalid.

-99

System error.

SOAP XML Request Format


stopUpload
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <mes:startUpload>
         <firmwareGroup>?</firmwareGroup>
         <firmwareImageName>?</firmwareImageName>
      </mes:startUpload>
   </soapenv:Body>
</soapenv:Envelope>

getFirmwareUploadStatus

This call returns a list of value pairs indicating the number of devices in the specified firmware group with a partial firmware upload.

Prototype


getFirmwareUploadStatus (devType, firmwareGroup)

Parameters

The following table describes the parameters in the interface.

Table 6. getFirmwareUploadStatus Parameters

Parameter

Options

Description

devType

cgmesh

The device to receive the firmware upgrade.

firmwareGroup

string

The firmware group of devices to receive the firmware upgrade.

Results

The following table describes the parameters in the response.

Table 7. getFirmwareUploadStatus Results

Value

Description

0

Success.

-1

devType not found or is not supported.

-2

firmwareGroup not found or is invalid.

-99

System error.

SOAP XML Request Format


getFirmwareUploadStatus
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <mes:getFirmwareUploadStatus>
         <firmwareGroup>?</firmwareGroup>
      </mes:getFirmwareUploadStatus>
   </soapenv:Body>
</soapenv:Envelope>

getFirmwareImageInfoList

This call returns a list with the name, version and number of devices that are running, uploaded and have a backup with this firmware version. The action status and scheduled reload date and time also return.

Prototype


getFirmwareImageInfoList (devType, firmwareGroup)

Parameters

The following table describes the parameters in the interface.

Table 8. getFirmwareImageListInfo Parameters

Parameter

Options

Description

devType

cgmesh

The device to receive the firmware upgrade.

firmwareGroup

string

The firmware group of devices to receive the firmware upgrade.

Results

The following table describes the parameters in the response.

Table 9. getFirmwareImageListInfo Results

Value

Description

-1

devType not found or is not supported.

-2

firmwareGroup not found or is invalid.

-99

System error.

SOAP XML Request Format


setBackupFirmwareImage
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <mes:setBackupFirmwareImage>
         <firmwareGroup>?</firmwareGroup>
         <firmwareImageName>?</firmwareImageName>
      </mes:setBackupFirmwareImage>
   </soapenv:Body>
</soapenv:Envelope>

setBackupFirmwareImage

This call sets the specified firmware image as the backup for the specified firmware group.

Prototype


setBackupFirmwareImage (devType, firmwareGroup, firmwareImageName)

Parameters

The following table describes the parameters in the interface.

Table 10. setBackupFirmwareImage Parameters

Parameter

Options

Description

devType

cgmesh

The device to receive the firmware upgrade.

firmwareGroup

string

The firmware group of devices to receive the firmware upgrade.

firmwareImageName

string

The firmware image name.

Results

The following table describes the parameters in the response.

Table 11. setBackupFirmwareImage Results

Value

Description

0

Success.

-1

devType not found or is not supported.

-2

firmwareGroup not found or is invalid.

-3

firmwareImageName not found or is invalid.

-99

System error.

SOAP XML Request Format


setBackupFirmwareImage
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <mes:setBackupFirmwareImage>
         <firmwareGroup>?</firmwareGroup>
         <firmwareImageName>?</firmwareImageName>
      </mes:setBackupFirmwareImage>
   </soapenv:Body>
</soapenv:Envelope>

scheduleReload

This call sets the date and time for a firmware upgrade of the specified firmware image and group.

Prototype


scheduleReload (devType, firmwareGroup, firmwareImageName, utcDateAndTime)

Parameters

The following table describes the parameters in the interface.

Table 12. scheduleReload Parameters

Parameter

Options

Description

devType

cgmesh

The device to receive the firmware upgrade.

firmwareGroup

string

The firmware group of devices to receive the firmware upgrade.

firmwareImageName

string

The firmware image name.

reloadGmtTime

string

The format is “yyyy-MM-ddTHH:mm:ss.”

utcDateAndTime

string

The format is “YYYY-MM-DD*HH:MM:SS.”

Results

The following table describes the parameters in the response.

Table 13. scheduleReload Results

Value

Description

0

Success.

-1

devType not found or is not supported.

-2

firmwareGroup not found or is invalid.

-3

firmwareImageName not found or is invalid.

-4

utcDateAndTime format is invalid.

-5

Bad firmware image.

-99

System error.

SOAP XML Request Format


scheduleReload
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <mes:scheduleReload>
         <firmwareGroup>?</firmwareGroup>
         <firmwareImageName>?</firmwareImageName>
         <reloadGmtTime>?</reloadGmtTime>
      </mes:scheduleReload>
   </soapenv:Body>
</soapenv:Envelope>