APIs for the Milli Manufacturing Tools

RMA Test and Milli Personalization APIs

Introduction

This page describes the APIs exposed by the Milli Manufacturing Tools application, including Milli Personalization, RMA Test, and Draw Test APIs. An Itron Partner can build their own custom applications by integrating with these APIs. For related information about the Reporting Module APIs , see here

This page contains the following sections: 

  • Prerequisites 
  • Milli Personalization APIs
    • Properties
    • Methods
    • Events
  • Sysvars
    • Sample Code
  • RF Test API
    • Command Class Methods
    • Command Class Events
    • ResponseAnalyzer Class Events
  • Draw Test API
    • DrawTestCommand Class Methods
    • DrawTestCommand Class Events

Prerequisites

The Milli Manufacturing Tools Application is a C#/.NET based application that requires Visual Studio IDE for development. To view the APIs and use them in a custom application, use the following steps to install Visual Studio Community on your development machine. 

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

 

Milli Personalization APIs

The Personalization APIs (PersonalizationBase and WiredPersonalization) are a set of .NET classes with a common Personalization Base class. The following combination of properties and methods provides the personalization feature:

Properties

  • ComPort – COM port representing the debug UART or the FSU
  • ConfigPath – File path for the Regional/Personalization Config to be applied to the Milli device
     

Methods

  • ApplyConfiguration – Applies the contents of ConfigScript to the UUT
  • ConfigScript – Deserializes the file referenced by ConfigPath
  • ValidateConfiguation – Validates the script referenced by ConfigPath, and sets ConfigScript
  • VerifyPersonalization – Verifies the settings applied on the Milli
     

Events

  • OnError –  When there is an error to be raised, registers a callback method with OnError of WiredPersonalization class
  • ConfigProcess – Raises after getting a response from Milli for each sysvar command
  • OnResetMilli – Raises to notify the user when the calling application needs to restart Milli manually
  • OnPersonalizationComplete – Raises after successful personalization of Milli

 

Properties

The following section describes the available configurable properties associated with the Milli Manufacturing Tools App. 

COMPort

Signature: public string ComPort { get; set; } –

This property is used to set COM Port name on which Milli is connected through UART cable.

 

ConfigPath

Signature: public string ConfigPath { get; set; }

This property is used to set metadata JSON file path

 

Methods

The following section describes the available configurable methods associated with the Milli Manufacturing Tools App. 

ApplyConfiguration

This method writes the sysvars on to Milli based on the metadata JSON values. This method takes a CancellationToken as an optional parameter. This token is used to cancel personalization process from UI/reference app.

Signature: public void ApplyConfiguration(CancellationToken ct)

 

ValidateConfiguration

This method reads the metadata JSON from the provided configuration path and validates it to confirm that metadata JSON is well formed. After validating metadata JSON, the Milli Personalization library de-serializes the JSON and prepares commands based on the sysvar value provided in metadata JSON.

Signature: public void ValidateConfiguration()

 

VerifyPersonalization

This method verifies the sysvars which have been written onto Milli. This API should be called on ‘OnPersonalizationComplete’ event, using the same personalization object.

Signature: public bool VerifyPersonalization();

 

 

 

Events

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

OnError

This event is raised if there is an error occurred on any command execution, and registers a callback method with OnError of WiredPersonalization class.

Create an object of WiredPersonalization class to access OnError event and register the call back method.

Implement the call back method and access the error as e.Message where ConfigProgressArgs is a sample Class.

 

ConfigProgress

This event is raised after getting a response from Milli for each sysvar command. Register a handler if you want to capture this event while processing each sysvar.

Create an object of WiredPersonalization class to access ConfigProgress event and register the event handler.

Implement the handler method and access the Result as e.Message where ConfigProgressArgs is a Class.

 

OnResetMilli

This event is raised to notify the user when the calling application needs to restart Milli manually.

Create an object of WiredPersonalization class to access OnResetMilli event and register the event handler

Implement the handler and intimate user to restart Milli by displaying any message or pop up box.

 

OnPersonalizationComplete

This event is raised after successful personalization of Milli. To acess OnPersonalization Colmplete event and register the event handler, create an object of WiredPersonalization class.

Implement the handler method which executes when the personalization process is completed successfully.

 

Sysvars

Following are the Sysvars supported by the PersonalizationBase API :

  • Sysvar1 – Network ID Pan ID (from config file)
  • Sysvar3 – Country code (from config file)
  • Sysvar7 - Routing Message Timing (hardcode to value ‘~’)
  • Sysvar8 – Operating mode (hardcode to value ‘~’)
  • Sysvar20 – Device Type (from config file)
  • Sysvar26 – MLMEKNOB1 (hardcode to value ‘4=0x00 0x00 0x2a 0x03’)
  • Sysvar27 – MLMEKNOB2 (hardcode to value ‘4=0x00 0x00 0x79 0x00’)
  • Sysvar29 – MLMEKNOB4 (hardcode to value ‘4=0x00 0x00 0x60 0x54’)
  • Sysvar34 – Listening Duration (hardcode to value ‘2=0x54 0x06’)
  • Sysvar35 – Persistent Observe (from config file)
  • Sysvar39 – Trap ID (from config file)
  • Sysvar41- Device IC Reboot (from config file)

 

Sample Code

The following code snippet is a sample usage of the WiredPersonalization class library. This code is meant to be used as an example and should be modified according to the specific use case to be implemented. 

 

RF Test API

The RF Test APIs (RMAlib.dll) are a set of .NET classes with a common Commands class. The following combination of methods and events perform RF Test.

Methods

  • Connect – Connects and enables access to the COM Ports to which Milli modules are connected
  • Disconnect – Disconnects the Milli modules from their associated COM Ports
  • StartRftest – Starts the RF test

 

Command Class Events

  • OnError – Registers a callback method when there is an error 
  • OnStepComplete Indicates there has been a successful step completion
  • RestartMilli – Prompts the user to restart the Milli
  • RFTestProgress –  Monitors the RF Test Progress

 

ResponseAnalyzer Class Events

  • OnRfTestComplete Raises an event when the RF Test Completes
  • OnErrorWhileParsingResponse – Captures the error encountered while parsing the response

 

Command Class Methods

Connect

The Connect method connects and starts access to the ComPort to which Milli modules are connected.

Signature: public bool Connect (string portName, int baud rate, PortType portType)

The input parameters are as follows:

  • portName as string
  • baud rate as int
  • portType as PortType

This is an enumeration parameter. Types include: UUT(Unit under test) and KGM(Known Good Milli Unit)

The Connect method returns a Boolean value which states whether the connection was a success or failure.

 

Disconnect

The Disconnect method disconnects the Milli modules from their associated COM Port.

Signature: public void Disconnect (PortType portType)

The input parameters are as follows:

  • portType as PortType
    • This is an enumeration parameter. Types include: UUT(Unit under test) and KGM(Known Good Milli Unit)

 

StartRfTest

The public void StartRfTest method starts the RF test. The command starts the RF server on the Known Good Milli Unit. It then starts the actual RF test on the UUT.

Signature: public virtual void StartRfTest (ResponseAnalyzer resp)

Before performing the RF Test, ensure that both the Milli Units are connected.

The input parameters are as follows:

  • The object of ResponseAnalyzer class processes the response from Milli Unit and raises the appropriate events.

 

    Command Class Events

    OnError

    This is an event raised if there is an error occurred on any command execution, register a callback method with OnError of commands class.

    Create an object of Commands class to access OnError event and register the call back method.

    _commands.OnError += Commands_OnError;

    Implement the call back method and access the error as e.Error where ErrorEventArgs is a class.

    public string Error { get; set; }

    public void Commands_OnError(EventsHandler.ErrorEventArgs e)

            {

                Error = e.Error;

     }

     

    OnStepComplete

    When there is a step complete to be raised on successful step completion ex:, “UUT Connected” message on successful connection of UUT, register a callback method.

    Create an object of Commands class to access OnStepComplete event and register the call back method.

     _commands.OnStepComplete += Commands_OnStepComplete;

    Implement the call back method and we will now access the Result as e.Result where StepCompleteEventArgs is a Class.

    public string Message { get; set; }

    private void Commands_OnStepComplete( EventsHandler.StepCompleteEventArgs e)

    {

                Message = e.Result;

    }

     

    RestartMilli

    When an event needs to be raised to prompt user to restart the Milli.

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

     _commands.RestartMilli += Commands_RestartMilli;

    Implement the call back method and access the Message as e.Message where RestartMilliForSetBootEventArgs is a class.

    public string Message { get; set; }

      private void Commands_RestartMilli( EventsHandler.RestartMilliForSetBootEventArgs e)

            {

                Message = e.Message;

    }

     

    RFTestProgress

    This event  monitors RF Test Progress.

    Create an object of Commands class to access the RFTestProgress event and register the call back method.

     _commands.RFTestProgress += MonitorRFTestProgress;

    Implement the call back method and access the status as e.status where RFTestProgressEventArgs is a class.

    public string RFProgressBarStatus { get; set; }

      private void MonitorRFTestProgress(EventsHandler.RFTestProgressEventArgs e)

            {

                RFProgressBarStatus = e.status;

    }

     

    ResponseAnalyzer Class Events

    OnRfTestComplete

    This is an event raised when the RF Test is Completed. Register a callback method in the way described below.

    Create an object of the ResponseAnalyzer class to access OnRfTestComplete event and register the following callback method:

     _responseAnalyzer.OnRfTestComplete += ResponseAnalyzer_OnRfTestComplete

    Implement the callback method and access ResponseData as e.ResponseData, where RFTestReadResultEventArgs is a class:

    private RFTestResponseData _rfTestResponseData;

    private void ResponseAnalyzer_OnRfTestComplete( EventsHandler.RFTestReadResultEventArgs e)

            {

                _rfTestResponseData = e.ResponseData;

    }

     

    OnErrorWhileParsingResponse

    To capture the error encountered while parsing the response, a callback method must be registered in the way described below. 

    Create object of ResponseAnalyzer class to access OnErrorWhileParsingResponse event and register the following callback method:

    _responseAnalyzer.OnErrorWhileParsingResponse += _responseAnalyzer_OnErrorWhileParsingResponse;

    Implement the callback method and access the data as e.data where RFTestErrorEventArgs is a class.

    private RFTestResponseData _rfTestResponseData;

    private void _responseAnalyzer_OnErrorWhileParsingResponse( EventsHandler.RFTestErrorEventArgs e)

            {

                _rfTestResponseData = e.data;

    }

     

    OnErrorWhileParsingCfgResponse

    To capture the error encountered while parsing the configuration response to fetch the MAC Address of the UUT, a callback method must be registered in the way described below. 

    Create an object of the ResponseAnalyzer class to access OnErrorWhileParsingCfgResponse event and register the following callback method:

    _responseAnalyzer.OnErrorWhileParsingCfgResponse += _responseAnalyzer_OnErrorWhileParsingCfgResponse;

    Implement the callback method and access the data as e.data, where EventsHandler.ErrorEventArgs is a class.

    String _cfgError = string.Empty;

    private void _responseAnalyzer_OnErrorWhileParsingResponse( EventsHandler.ErrorEventArgs e)

            {

                _ cfgError = e.data;

    }

    Draw Test API

    The Draw Test functionality in MMT changes the mode on Milli to idle. Two options are available to wake it up:

    1. By Time - the "wake up after a time period" option
      • In this case, you must define the time period for how long the MMT should remain in idle mode. During this time, the operator manages the current that is managed by the Milli in its current state. 
    2. Pin change - also known as toggling the logic state on the pin
      • ​​​​​​​In thise case, you must define which PIN MMT should use to wake up the Milli with. The test starts, the Milli goes into Idle mode while you measure the current. Upon completion, the tester tells MMT that they have finished the test. MMT then executes a command against Milli which toggles the logic state. 

     

    The Draw Test APIs (RMAlib.dll) are a set of .NET classes with a common DrawTestCommand class. The following combination of methods and events perform Draw Test. You can use these commands as an alternative to using the UI, and/or to automate processes. 

    Methods

    • Connect – connects and enables access to the COM Ports to which Milli modules are connected
    • ApplyConfiguration – configures the Milli for the draw test
    • Disconnect – disconnects the Milli modules from their associated COM Ports
    • PrepareDrawTestCommand – (for the time method) prepares power configuration command to wake up Milli after time interval, which executes on Milli to start draw test
    • PrepareDrawTestCommand – (for pin change method) prepares power configuration command to wakeup with a pin change, which executes on Milli to start draw test

     

    Events

    • OnError – when there is an error to be raised, register a callback method with OnError of DrawTestCommand class
    • OnComplete – when the Draw test is complete, register a callback method with OnComplete of DrawTestCommand class
    • OnResetMilli – raised to notify the user when the calling application needs to Milli to be manually restarted by the user
    • OnProcessing – raised on successful processing of each command
    • OnWakeUp – raised when Milli wakes up from power config mode

     

    DrawTestCommand Class Methods

    Connect

    The Connect method connects and starts access to the ComPort to which Milli modules are connected.

    Signature: public bool Connect (string portName, int baud rate)

    The input parameters are as follows:

    • portName as string
    • baud rate as int

     

    The Connect method returns a Boolean value which states whether the connection was a success or failure.

    Execute the Connect method after executing the SetBoot method.

    Note: Connect method should be called before executing any other command.

     

    ApplyConfiguration

    This method configures Milli in the Power Config mode to start the draw test.

    Signature: public void ApplyConfiguration(List<Command>cmdList, cancellationtoken ct)

    The input parameters are as follows:

    • Command list – created using PrepareDrawTestCommand method.
    • cancellation token.

     

    Disconnect

    The Disconnect method disconnects the Milli modules from their associated COM Port.

    Signature: public void Disconnect ()

     

    PrepareDrawTestCommand (with wake up time)

    This method creates the draw test command to wake up the Milli after the time interval is executed on tje Milli to start the draw test.

    Signature: public List<Command> PrepareDrawTestCommand(int? wakeuptime)

    The input parameters are as follows:

    • Wake up time in seconds

     

    PrepareDrawTestCommand (with wake up pin id)

    This method toggles the logic state of the selected Pin to wake up Milli so that the draw test can be performed.

    Signature: public List<Command> PrepareDrawTestCommand(int? wakeupPinID, Constant.LogicState? logicState)

    The input parameters are as follows:

    • Wake up as pin ID
    • Logic state – low/high

     

    TurnOnSfl

    This method is used to turn on the serial flash once Milli wakes up from Power Config mode.

    Signature: public void TurnOnSfl()

     

    DrawTestCommand Class Events

    OnError

    This event is raised if an error occurs during any command exeuction. In this case, register a callback method with OnError of DrawTestCommand class.

    Create an object of DrawTestCommand class to access the OnError event and register the following callback method:

    _commands.OnError += Commands_OnError;

    Implement the callback method and access the error as e.Error, where DrawTestEventArgs is a class.

    public string Error { get; set; }

    public void Commands_OnError(DrawTestEventArgs e)

            {

                Error = e.Error;

     }

     

    OnComplete

    The OnComplete event is invoked when the Milli is successfully configured for draw test.

    Create an object of DrawTestCommand class to access OnComplete event. Then register the following callback method:

     _commands.OnComplete += Commands_OnComplete;

    Implement the callback method. A dialog box with Pass/Fail/Cancel buttons displays.

    private void Commands_OnComplete(DrawTestEventArgs e)

    {

                //

    }

     

    OnResetMilli

    This event raises to prompt the user to restart the Milli Device.

    Create an object of DrawTestCommand class to access OnResetMilli event and register the following callback method:

     _commands.OnResetMilli += Commands_RestartMilli;

    Implement the callback method and access the Message as e.Message, where EventArgs is a class.

    public string Message { get; set; }

      private void Commands_RestartMilli(object sender, EventArgs e)

            {

                //Prompt user to restart milli

    }

     

    OnProcessing

    This is an event raised to monitor the Progress while Milli is being configured for the Draw Test.

    Create object of DrawTestCommand class to access OnProcessing event and register the call back method

     _commands.OnProcesing += MonitorDrawTestProgress;

    Implement the call back method where EventArgs is a class.

      private void MonitorDrawTestProgress (object sender, EventArgs e)

            {

                //increment the progress.

    }

     

    OnWakeUp

    This event raises to inform the user that Milli has woken up from Power Config mode.

    Create an object of the DrawTestCommand class to access OnWakeUp event. Then register the following callback method:

     _commands. OnWakeUp += DrawTest_OnWakeUp;

    Implement the callback method where EventArgs is a class.

      private void MonitorDrawTestProgress (object sender, EventArgs e)

            {

                //prompt the user

    }