North Bound API User Guide for the Cisco IoT Field Network Director, Releases 3.x and 4.x

Bias-Free Language

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.

Book Contents

Find Matches in This Book

Results

Updated:: May 7, 2017

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
Firmware Upgrade API Method Calls

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
stopUpload
getFirmwareUploadStatus
getFirmwareImageInfoList
setBackupFirmwareImage
scheduleReload

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>

Was this Document Helpful?

Feedback

Contact Cisco

Open a Support Case
(Requires a Cisco Service Contract)