APIs for Milli Firmware Upgrade Application

Introduction 

This page describes the APIs exposed by the Milli Firmware Upgrade application. An Itron partner can build their own custom applications by integrating with these APIs. These APIs allows users to upgrade firmware images on their Milli devices and  execute Set Boot-Set Image commands in a wired mode on up to three devices at a time.

Prerequisites

To execute the methods associated with the Milli Firmware Upgrade application, make sure you have the application installed and running on your machine. Refer to the Milli Firmware Upgrade page for further details and instructions. 

The Milli Firmware Upgrade Application is a C#/.NET based application that requires Visual Studio IDE for development. To access the APIs and use them in a custom application:

  • Download Visual Studio Community 2017, double-click on the installer, and follow the steps to install.
  • Select .Net Desktop Development and click Install. See the following image for reference. 

 

 

Milli Firmware Upgrade APIs

The Firmware Upgrade APIs are a set of .NET classes with a common FwUpdateCommands class. The following combination of methods and event handlers perform Firmware Upgrade:
 

  • Methods
    • GetMacAddress –​ reads the MAC address of the Milli connected with COM port
    • SetBoot – creates the SETBOOT command to set an image version
    • UploadSingleFirmwareImage – uploads the single firmware image to a specific slot of Milli
    • UploadEntireFirmwareImage – uploads the entire firmware image (all the three images) on Milli

 

  • EventHandlers
    • OnError  raised when there is an error encountered
    • OnStepComplete – raised when there is a step complete to be raised on successful step completion
    • RestartMilli – raised to notify the user to restart Milli manually
    • FwUploadProgress – raised to notify the progress of Firmware Upgrade to the user
      • ​This is part of RunSioLoad class events

 

Methods

The following section describes the available configurable methods associated with the Milli Firmware Upgrade App. 

GetMacAddress

public virtual string GetMacAddress(string portName)

This method retrieves the MAC Address of Milli connected on a particular port if the Milli is on Hardware Test or Self Test Image. A series of stars (" **************** ") are returned if the Milli is operating on Standard Operating Image or if there is no Milli connected.

Input parameters include:

  • portName: Port to which Milli is connected

 

SetBoot

public virtual bool SetBoot(string sioLoadPath, string portName, string slotNumber, RunSioLoad _runSioLoad)

This method creates the SETBOOT command to set an image version.

Input parameters include:

  • sioLoadPath: Path where the sio_load.exe is placed
  • portName: Port to which Milli is connected
  • slotNumber: Image Slot on which Set Boot needs to be performed (can be 1 or 2 or 3)
    • 1 - Hardware test image
    • 2 - Standard Operating image
    • 3 - Self Test image
  • _runSioLoad : Object of RunSioLoad class which starts the processes\runs the command

 

This method has a Boolean return type which returns true when there has been a successful SetBoot operation. Corresponding logs are captured for each process and events are raised on step completion or if any errors are encountered.

 

UploadSingleFirmwareImage

public virtual bool UploadSingleFirmwareImage(string sioLoadPath, string fwImagePath, string portName, string imageSlot, RunSioLoad _runSioLoad, string mac)

This method uploads the single firmware image to a specific slot of Milli. This is usually used for uploading a Standard Operating Image.

Input parameters include:

  • sioLoadPath: Path where the sio_load.exe is placed
  • fwImagePath: Firmware Image file to upgrade Milli
  • portName: Port to which Milli is connected.
  • imageSlot: Image Slot on which Firmware upgrade needs to be performed (can be 1 or 2 or 3)
    • ​1 - Hardware test image
    • 2 - Standard Operating image
    • 3 - Self Test image
  • _runSioLoad : Object of RunSioLoad class which starts the processes\runs the command
  • mac: MAC address of the Milli on which Firmware Upgrade is being performed

 

This method has a Boolean return type which returns true in the case of a successful Firmware Upgrade. Corresponding logs are captured for each process and events are raised on step completion or if any errors are encountered.

 

UploadEntireFirmwareImage

public virtual bool UploadEntireFirmwareImage(string sioLoadPath, string fwImagePath, string portName, RunSioLoad _runSioLoad, string mac)

This method uploads the entire firmware image (all three images) onto the Milli.

Input parameters include:

  •  sioLoadPath : Path where the sio_load.exe is placed
  • fwImagePath : Firmware Image file to upgrade Milli
  • portName : Port to which Milli is connected.
  • _runSioLoad : Object of RunSioLoad class which starts the processes\runs the command
  • mac: MAC address of the Milli on which Firmware Upgrade is being performed

 

This method has a Boolean return type which returns true in the case of a successful Firmware Upgrade. Corresponding logs are captured for each process and events are raised on step completion or if any errors are encountered.

 

EventHandlers

The FwUpdateCommands class exposes the following events. The calling application can register a call back method and invoke the events.

OnError

When there is an error to be raised, register a callback method with OnError of FwUpdateCommands class.

Create object of FwUpdateCommands class to access OnError event and register the callback method

_fwUpdateCommands.OnError += _fwUpdateCommands_OnError;

Implement the callback method and we will now access the error as e._error where ErrorEventArgs is a Class.

public string Error { get; set; }

private void _fwUpdateCommands_OnError(FwUpdateCommands sender, EventsHandler.ErrorEventArgs e)

        {

            Error = e._error

               }

 

OnStepComplete

OnStepComplete: To notify step complete to the user on successful step completion, register a callback method with OnStepComplete of FwUpdateCommands class.

For example: To raise “Firmware upload Done on COM3 “

Create object of FwUpdateCommands class to access OnStepComplete event and register the call back method:

_fwUpdateCommands.OnStepComplete += _fwUpdateCommands_OnStepComplete;

Implement the callback method, and then access the Result as e._result where StepCompleteEventArgs is a Class.

public string Message { get; set; }

private void _fwUpdateCommands_OnStepComplete(FwUpdateCommands sender, EventsHandler.StepCompleteEventArgs e)

        {

            Message = e._result;           

        }

 

RestartMilli

To notify user to restart Milli manually, register a callback method with RestartMilli of FwUpdateCommands class.

Create object of FwUpdateCommands class to access RestartMilli event and register the call back method:

_fwUpdateCommands.RestartMilli += _fwUpdateCommands_RestartMilli;

Implement the call back method, then access the Message as e._message where RestartMilliForSetBootEventArgs is a Class.

public string Message { get; set; }

private void _fwUpdateCommands_RestartMilli(FwUpdateCommands sender, EventsHandler.RestartMilliForSetBootEventArgs e)

{

Message = e._message;

}

 

 

The RunSioLoad class exposes the following event.

FwUploadProgress

To notify the progress of Firmware Upgrade to the user, register a callback method with FwUploadProgress of RunSioLoad class.

Create object of RunSioLoad class to access FwUploadProgress event and register the call back method:

_runSioLoad.FwUploadProgress += _runSioLoad_FwUploadProgress;

Implement the callback method as below

public int ProgressBarForEntireFwImage { get; set; }

private void _runSioLoad_FwUploadProgress(RunSioLoad sender, EventsHandler.FwUploadProgressEventArgs e)

        {

          

            ProgressBarForEntireFwImage = ProgressBarForEntireFwImage + 1;

        }