Introduction 

This page provides an overview of how Agents will operate using function calls to the DI Agent (SDK) API.  

 

A detailed description of the Agent API and the supporting Common Libraries can be found on the pages entitled: DI Agent API and DI Agent Common Library respectively. 

 

Startup Process 

Required operations are labeled with a “REQ”. 

  1. REQ: At startup, Agents must first register themselves using a call to: “ApiRegisterAgent”. This call must be successfully completed before calling any other functions. 

  2. The Agent should then read the current configuration for all the relevant implemented features using a call to: “ApiGetAndSubscribeToConfiguration”. In addition, if the Agent needs to receive configuration updates from upstream systems while running, it should register its configuration callback via the same call.  

  3. For system-provided values that are fixed (non-periodic data), the Agent should use a call to: “ApiGetData” to retrieve these values at startup and store them in memory if necessary. An Agent should not need to retrieve these fixed values more than once. 

  4. For (sampled) periodic data, such as Phase Voltage, call: “ApiSubscribeToPeriodicData” to inform the system which Logical ID’s (LID’s) are desired. This is also known as a Subscription and results in a callback, either at a fixed period or when the data changes. A full list of available LIDs see: DI SDK Available Logical IDs (LIDs). 

 

Most of the API calls return an enum value defined by: “AgentApiReturnType”. These enum values and their meanings are described on  DI Agent API

Choose your Subscription (Callback) Type 

 

  • ON_DATA_CHANGE_ONLY: Called when the data (e.g. phase voltage) changes, but never more than once per second for performance reasons. If the data never changes this callback is not called. 

  • ON_PERIOD_ONLY: Called when the period expires but never more than once per second. An empty vector is provided if nothing has changed. 

  • ON_DATA_CHANGE_AND_PERIOD: Called when the period expires but only if the data has changed and never more than once per second. 

  • ON_DATA_CHANGE_OR_PERIOD: Called when the data changes, but never more than once per second, or if the period expires without a change. An empty vector is provided if nothing has changed. 

 

 

Runtime Process 

 

  1. Once startup is complete, Agents can now run as they wish. However, there is a strongly suggested methodology. This begins with the Subscription (callback) mechanism above. 

  2. The callback serves as both a timer and as a notifier of changed data. Most Agents should be able to be designed to only run on this mechanism. 

  3. Agents will have globals for all the values they are reading from the meter. The available list will be published, and the types explicitly known. 

  4. With the callback, the Agents get an array of LID values and a count. For each LID in the LID array, the LID number is checked, and the value copied to the respective global. 

  5. Process the data as required. This is the most important step as it’s where the Developer will implement their particular DI algorithm such as Broken Neutral Detection or Load Disaggregation. It is expected that the Developer will spend most of the development time in this step.  

  6. If an Agent needs to raise an event or alarm to upstream systems, it can call “ApiLogHistoryEvent” or “ApiLogHistoryEventWithTimeStamp” to send the event.  

  7. If an Agent needs to publish data to upstream systems, it can call: “ApiWriteAgentDataForUpstreamSystem” to send this data. 

 

The supplied Reference Agent implements all of the above steps albeit with a very simple DI algorithm. In greater detail, it subscribes to periodic (1 second) Voltage data. If the voltage drops below a threshold of 231V it raises an “Open” event which is sent to the Azure IoT Hub. When the voltage returns to a value above 231V the Reference Agent raises a “Close” event. 

Metrology Simulation 

 

The DI SDK provides a basic comma separated variable (csv) file-driven metrology simulator. If a csv file exists in the Ubuntu VM directory: “/usr/share/itron/metsimfiles”, the simulator will automatically start when an agent starts up, reading out each row of the csv every second and updating the data (LIDs) that has changed. 

DI Desktop SDK Metrology Simulator Guide describes how to configure and use the Metrology Simulator. 

 

Agent Configuration 

 

The relevant requirements are: 

  • Configuration should be permitted whether an Agent is running or not. 

  • Configuration is done on a per-feature basis. 

  • Configuration must support multi-cast and peer-to-peer configuration updates from the head-end system, as well as updates via local tools. 

 

In order to fulfill these requirements, the following configuration methods are provided: 

  1. The Agent starts and requests the configuration for all features implemented by that Agent. 

  1. Once the Agent has consumed the configuration, it registers with the “configuration update callback”, so it can receive any updates that are processed while the Agent is running. 

  1. Configuration updates will be performed via a write to a COSEM object. 

  1. These writes will commit a configuration to the feature configuration table. 

  1. On the meter, the DataServer will receive a notification that updates have been made and will check for updated configurations. At this point, it will determine whether the update that was made was relevant to any running agents that have registered with the configuration update callback. If it finds any, it will send an update to those Agents. 

 

 

                                            DI Desktop SDK Feature Updater

 

Introduction

 

DI Agents are capable of being reconfigured while they are running. This is done by pushing new configurations on a per-feature basis from the head-end system or via local tools.
 
This functionality can be simulated in the SDK. Updated configurations can be manually committed to the meters feature configuration table. If a configuration callback is registered (using the “ApiRegisterConfigurationCallback” function) then a UDP port listener is opened on a special port. This listener will accept any message directed at the Ubuntu VM’s IP address and that port. In order to accept the message and direct it to the agent, the first four bytes of the message must be the Agent Id of the targeted agent. If this comparison passes then the rest of the message is passed through to the registered callback, which prompts the SDK to retrieve the current configuration from the feature configuration table for all the registered features and to pass those back to the agent.
 
A python program known as the “Feature Updater” has been developed to automatically perform the logic discussed in the above paragraph. This document describes how to install and use the Feature Updater.

 

Step A – Install the Feature Updater

This section contains the steps to install the Feature Updater which is used to update the configuration of a feature on a running DI Agent.

 

Step 1 – Install Python and Dependent Libraries

Install Python 3 and Pip3. This is done by:

  1. In a Terminal window, navigate to the dev user’s home directory using: “cd ~”.
  2. If not already installed, install Python 3, using: “sudo apt-get install python3”
  3. Install Pip3 using: “sudo apt-get install python3-pip”

 

Step 2 – Update the Common Library

Update two files in the Common Library. This is done by:

  1. Download the files: “config_parser.h” and “config_parser.cpp” by clicking here (link to files)
  2. In a Terminal window, copy the file” “config_parser.h” into the directory: “~/DistributedIntelligence/source/Agents/CommonLib/include” using: “cp config_parser.h ~/DistributedIntelligence/source/Agents/CommonLib/include”
  3. Copy the file: “config_parser.cpp” into the directory: “~/DistributedIntelligence/source/Agents/CommonLib/src” using: “cp config_parser.cpp ~/DistributedIntelligence/source/Agents/CommonLib/src”

 

Step 3 – Install the Feature Updater

Install the Feature Updater which is contained in the file: host_update_feature.py. This is done by:

  1. Download the file: “host_update_feature.py” by clicking here (link to file).
  2. In a Terminal window, from the dev user’s home directory, create a directory to hold the program using: “mkdir -p ~/Documents/DI/python/FeatureUpdater”
  3. Copy the “host_update_feature.py” into the newly created directory of step 2 using: “cp host_update_feature.py ~/Documents/DI/python/FeatureUpdater”.
  4. Make the: “host_update_feature.py” file executable using: “chmod 774 ~/Documents/DI/python/FeatureUpdater/host_update_feature.py”

 

Step B – Test a Feature Update

 

This section contains the steps to demonstrate a configuration update to the running Reference Agent. The Reference Agent generates “Open” events (alarms) when the voltage drops below the default Threshold Voltage of 231V and generates corresponding “Close” events when the voltage returns to a level greater than 231V. This test will demonstrate an update to this Threshold Voltage setting.

 

Step 1 – Run the Reference Agent

Run the Reference Agent and Metrology Simulator. This is done by:

  1. In a Terminal window, navigate to the “ThirdPartyReferenceAgent” directory using: “cd ~/DistributedIntelligence/source/Agents/ThirdPartyReferenceAgent”.
  2. Build and run the Reference Agent using: “sudo ./host_doall.sh”.

 

Step 2 – Monitor the Reference Agents Logs

Monitor the running Reference Agent’s debug log file: “2302fff1_log”. This is done in a separate Terminal window using: “tail -F /tmp/agent/2302fff1/2302fff1_log”. Observe that the occasional “Open” event is generated for Voltages that are less than the default Voltage Threshold setting of 231V. “Close” events are generated when the voltage returns to a level greater than the Voltage Threshold setting of 231V as per Figure 1.

​

Figure 1: The log file: “2302fff1_log” Showing an Open Event for a Voltage Less Than the Default Voltage Threshold Setting of 231V

 

Step 3 – Edit the Applicable Feature Configuration

Edit the configuration for Feature Id: 2303fff1. This is done by:

 

In a Terminal window, navigate to the Reference Agents “agents.d” directory using: “cd ~/DistributedIntelligence/source/Agents/ThirdPartyReferenceAgent/config/etc/agents.d”
Using a Terminal text editor such as vi or nano, edit the file: “2302fff1.2303fff1.xml” and adjust the “ThresholdVoltage” value to a higher value, such as 240V, in order to generate many more events as per Figure

                         

                 Figure 2: The Feature Configuration File: “2302fff1.2303fff1.xml” in the Terminal Text  Editor:  vi After Updating the “ThresholdVoltage” Value

 

Step 4 – Run the Feature Updater

Run the Feature Updater program. This is done by:

  1. In a Terminal window, navigate to the “FeatureUpdater” directory using: “cd ~/Documents/DI/python/FeatureUpdater”
  2. Run the Feature Updater program using: sudo ./host_update_feature.py -i /home/dev/DistributedIntelligence/source/Agents/ThirdPartyReferenceAgent/config/etc/agents.d/2302fff1.2303fff1.xml -a 587399153 as per Figure 3. Note that 587399153 is the Reference Agent’s Id in decimal.

                         

                     Figure 3: A Terminal Window after Successfully Running the Feature Updater

 

After a very short time a configuration update will be observed in the log file: “2302fff1_log” as per Figure 4. Note that in Figure 4 the “ThresholdVoltage” has changed to 240V.  It should also be observed in the log file: “2302fff1_log” that “Open” events are generated for Voltages that are less than the new Voltage Threshold setting of 240V and that there are many more events as per Figure 5.

 

                     

                    Figure 4: The log file: “2302fff1_log” Showing the new “ThresholdVoltage” of 240V

 

                 

              Figure 5: The log file: “2302fff1_log” Showing an Open Event for a Voltage Less Than the                                   Updated Voltage Threshold Setting of 240V