FAI Lite Agent

You can configure the FAI Lite Agent to export Raw Value data samples from the Wavelet to CSV-formatted files or directly to your SCADA system via DNP3 or OPC-UA. You configure the MQTT Broker to communicate with the Wavelet and with the Agent.

Prerequisites 

Configuring  FAI Lite  

Configure the Agent for CSV Output Files

Configure the Agent for DNP3

Configure the MQTT Broker 

Configure other Agent parameters (Metadata, Serilog, Logging, StoreDumps)

Integrate Raw Value data with SCADA 

Configuring devices for MQTT communication  

Appendix A

Opening the MQTT Ports 

templates.json file

mappings.json file 

metadata.json file

Stopping, Starting, and Uninstalling the Agent 

Information About Popular MQTT Brokers 

Appendix B

CSV parameters in apsettings.json

DNP3 parameters in appsettings.json

More DNP3 parameters in appsettings.json

MQTT section in appsettings.json

Metadata parameters for CSV and OPC UA

Serilog area in appsettings.json

StoreDumps area in appsettings.json

Prerequisites 

You must have a basic understanding of MQTT. To learn about MQTT basics, features, and to watch video tutorials, see MQTT Essentials. 

You must have the specifications documentation for the sensors that sample the data. Information about the communication protocol that the sensor uses is needed when you integrate Raw Value data into your SCADA system.

An MQTT Broker must be installed and configured according to the following points: 

• MQTT Broker must be accessible from outside and from inside your network. 

• Open port 8883 (secured) in the MQTT Broker’s host machine in the Firewall. You might also want to open port 1883 (unsecured) or other ports, according to your use case.   

• MQTT protocol with TLS communication must be enabled – certificates must be signed (CA or self-signed), and the Broker must be configured to use them. 

• You must know the address and port number of the MQTT Broker’s host machine. 

• If the Broker is configured to use several usernames and passwords, you must know those credentials. 

Wavelet devices requirements: 

• The devices must have Firmware version 2.29x or newer. 

Agent requirements: 

• The host computer must have a Microsoft® Windows® Server 2012, 64-bit or Windows 10 platform, 64-bit installed. 

• Contact support@ayyeka.com to get the Agent .MSI package installer file. Copy the installer file to your local computer, and then run the installer. 

• The Agent must be able to communicate with the MQTT Broker port (the default ports 8883 and, if needed, 1883)

• The Agent must have read-write access to your file systems. 

• Microsoft .NET 5 must be installed on the host computer. 

Configuring  FAI Lite  

In this section, you’ll configure your MQTT Broker to communicate with both the Wavelet device and the Agent. You’ll also configure the Agent either to work with your SCADA system or to export data as CSV files on your local computer.  

1. Go to the directory where you installed the Agent. 

2. Open the appsettings.json file with a text editor.  

3. Edit DeviceQueueItems according to your needs.  

Each device queue holds items (data samples and device metadata) from each transmission. When the number of items reaches the value that you define (the queue is full), the Agent stops receiving information from the MQTT Broker until the queue is no longer full.

  4.   To send values to CSV output files, configure the Agent for CSV output files. 

In the CSV area, edit parameters to format the file, partition data into directories and files, define file naming conventions, and filter data. For parameter details, click CSV parameters in apsettings.json.

  5.   To send values to DNP3 client, configure the Agent for DNP3.

1. 1. Go to the DNP3 area. Edit the following parameter values to configure the number of core threads and to define the template file that will map each channel to an DNP3 Input type. For parameter details, click DNP3 parameters in appsettings.json.
   2. Configure the following parameters for every outstation. For parameter details, click More DNP3 parameters in appsettings.json.

6.   Configure communication with the MQTT Broker.

In the MQTT  section, configure the communication parameters between the Broker and Agent. For parameter details, click MQTT section is appsettings.json.

7.   Configure other Agent parameters.

1. 1. (CSV and OPC-UA only) In the Metadata section, you designate a file (default name is metadata.json) to store metadata that can add descriptive information regarding the devices and their channels.  This designated metadata file contains definitions for user-defined custom attributes at both the device and channel levels. These user-defined custom attributes can be used in your CSV output files or in the OPC-UA data. For details, see Metadata parameters for CSV and OPC-UA.
   2. In the  Serilog section, edit the following parameter values to define the log directory, the logging level, and how often the logs are rolled over.  For details, see  Serilog area in appsettings.json.
   3. The Logging section is for Windows event logs that are displayed in the Event Viewer in case of Warning and above. It is recommended to not change these settings. 
   4. In the StoreDumps section, edit the following parameter values that define where the Agent will put dump files. The dump files contain Raw Value data in binary format. For details, see StoreDumps area in appsettings.json.

If needed, you can re-upload the dump files to the MQTT Broker to “replay” the information. For example, if your data was initially going to CSV files, you can use the dump files to upload the same data to the MQTT Broker and send it to your SCADA system via DNP3.

  8.   Restart the Agent.

  9.   Integrate the Raw Value data from specific channels with your SCADA system. 

For mapping details, see Integrate Raw Value Data with SCADA. Be sure to have on hand the specifications documentation for the sensors that sample the data.

Configuring the Wavelet Devices for MQTT Communication 

Each device needs to be configured to connect with the MQTT Broker in your network. The Wavelet can then publish Raw Value sample data as messages to the MQTT Broker. If the device is new, it will be configured before shipment according to your request. Otherwise, you must connect the device to FAI Pro or FAI Local to configure it in the UI. 

If the device is still connected to FAI Pro or FAI Local, do the following steps in the UI:  

1. Open the Advanced Device Configuration section. 

2. Click GSM. Set the following parameter values: 

• • gsm_mqtt_enable: 1 

  • MQTT Server Address - The IP address or name of the server where your MQTT Broker is installed. 

  • MQTT Server Port - 8883 for TLS.  

• • Use SSL: 1 

The GSM settings are updated after the Wavelet’s next transmission. The device will begin sampling data. As soon as the MQTT device settings are configured, the Raw Value data will be sent to your MQTT Broker. 

Appendix A

Opening the MQTT Port

You must open port 8883 on your Windows platform where you installed the MQTT Broker to enable the MQTT Broker to communicate with the device and Agent.

The following steps are an example of how to open the port. Review these steps with your IT Department. 

1. In the Search Command Prompt field of your desktop, type Run. The Run window opens.
     

2. In the Open field, type firewall.cpl, and then click OK. The Windows Defender Firewall window opens. 
   

3. In the left pane, click Advanced Settings. The Windows Defender Firewall with Advanced Security window opens.
   

4. In the left pane, click Inbound Rules. In the Actions pane, click New Rule... 
   
   

  5.   In the Rule Type window, select Port, and then click Next.

  6.   In the Protocol and Ports window, select TCP and Specific local ports. Type in 8883 in the adjacent field. Click Next. 
 

  7.   In the Action window, do the following steps: 

                  a. In the right pane, click Action, select Allow the connection, and then click Next.

                  b. In the right pane, click Profile, select all three check boxes, and then click Next. 

                 c. In the right pane, click Name, and then type in a name for your MQTT port rule. For example, you might type in MQTT Service Port. Click Finish. 

The new MQTT port rule is now listed in the Inbound Rules area of Windows Defender Firewall with Advanced Security window. 

templates.json file 

The templates.json file maps the devices, channel type, and channel number to a unique DNP3 input type and index number.

The templates.json file has the following sections:

• The DefaultVariations section defines the DNP3 variations for BinaryInput, AnalogInput, and Counter that are used for static and event data

Static data refers to a point’s current or most recently recorded value. For BinaryInput, “static data” refers to the present on/off condition. For AnalogInput, static data contains the value of an analog measurement at the instant it is transmitted. Static data is pulled from the outstation and has no timestamp.

Event data is associated with changes in points, such as state changes, measurement at some threshold, or an analog input leaving its defined threshold range. Event data is pushed by the outstation as an unsolicited response and does include a timestamp. 

Variations are different formats for data types in a group. Each group has a set of variations. The following table shows what group numbers, variations, and data types are in each input type. 

• The AnalogInputs, BinaryInputs, and Counter sections map the device's channel type to a specific DNP3 input type. The channels of each device are mapped to a specific DNP3 index, based on the device's channel type. Each DNP3 input type section contains the following information to map all channels of each device :
  • Source - Defines a device's channel type and channel number. 
  • Active - By default, Active=true to include the Source in the templates.json file. If Active=false, the Source is not included in the mapping file.

• Destination - Defines an index and class for DNP3 based on the defined Source properties.
  • Index is a sequential number that gives each Source a unique identifier.
  • Class is  a way to organize your data for optimized DNP3 polling because the response polling messages are small and efficient. The value of Class can be 1-3.

Typically, all devices are assigned to Class1, but you can group your devices according to polling frequency needs. For example, if you configure your SCADA to poll specific devices every 10 seconds, you can assign these devices to Class1. If the SCADA polls other devices every 10 minutes,  you can assign those devices to Class2.

Example of AnalogInputs

"AnalogInputs": [ 
      { 
        "Source": { 
          "ChannelType": "Serial", 
          "ChannelNumber": 0 
        }, 
        "Destination": { 
          "Index": 0, 
          "Class": "Class1" 
        } 
      } 
{ 
        "Source": { 
          "ChannelType": "Analog", 
          "ChannelNumber": 0 
        }, 
        "Destination": { 
          "Index": 1, 
          "Class": "Class1" 
        } 
      } 
] 

In this example, data coming from a VBAT (external power voltage) technical stream on channel 2 will be mapped to BinaryInputs, Type=Power, and Index=0.  

The next data is from the TEMP technical stream. This stream has two channels: 

• • Channel 0 is for temperature. It will be mapped to BinaryInputs, Type= TemperatureHumidity, and Index=1. 

  • Channel 1 is for internal humidity. It will be mapped to BinaryInputs, Type= TemperatureHumidity, and Index=2. 

"BinaryInputs": [ 
      { 
        "Source": { 
          "ChannelType": "Power", 
          "ChannelNumber": 2 
        }, 
        "Destination": { 
          "Index": 0, 
          "Class": "Class1" 
        } 
      } 
{ 
        "Source": { 
          "ChannelType": "TemperatureHumidity", 
          "ChannelNumber": 0 
        }, 
        "Destination": { 
          "Index": 1, 
          "Class": "Class1" 
        } 
      } 
{ 
        "Source": { 
          "ChannelType": "TemperatureHumidity", 
          "ChannelNumber": 1 
        }, 
        "Destination": { 
          "Index": 2, 
          "Class": "Class1" 
        } 
      } 
] 

In the default templates.json file supplied by Ayyeka, the inputs are configured according to common use. It is recommended to make the value of Destination:Index sequential according to the input type (AnalogInputs, BinaryInputs, and Counter).  

The following table lists the mapped ChannelType name, ChannelNumber range, Index range, and Class that you can use in the default templates.json file.

You may create your own customized template to meet your needs. You can have multiple templates in order to group devices according to their function.  Each user-defined template is added to the default templates.json file.

mappings.json file  

Every outstation must have a mapping file assigned to it. The file configures each device that is assigned to that outstation to use a specific template. The file also defines an offset for each device to distinguish the channels of each device from the channels of the other devices in the outstation.  

By default, one outstation is defined in the appsettings file. The default mappings file associated with the default outstation is mappings.json. A maximum of 650 devices may be assigned to an outstation. Therefore, if you have more than 650 devices, additional outstations must be defined in the appsettings.json file. Each outstation must have a unique mappings file.

[ 
  { 
    "AKID": "24A04F085C80A4B0", 
    "TemplateName": "DefaultTemplate", 
    "Offset": 0 
  }, 
  { 
    "AKID": "24A04F085C80A9D0", 
    "TemplateName": "DefaultTemplate", 
    "Offset": 100 
  } 
]  

metadata.json file

You can define custom attributes in order to add descriptive information about the devices and their channels. These custom attributes can be used in your CSV output files or in the OPC-UA data.  

In CSV, you can later filter data based on custom attribute values. Alternatively, you can set CustomAttributesOutputNoData=false to exclude it from the output file. 

1. Open the metadata.json file with a text editor, and then do the following steps:  

   1. In the CustomAttributes area, define as many attributes for devices and channels as needed. 

• • • In the DeviceCustomAttributes area, define as many Attributes as you need to describe the device. For example: name, serial.number, location, installer, address, account.  

    • In the ChannelCustomAttributes area, define as many Attributes as you need for channels. For example: name, units, sensor.name, minimum, maximum.  

          b.   In the DeviceMapping area, add each device with its channels, AKID, and Attributes.

The device attributes must be the same that you defined in the DeviceCustomAttributes area in the previous step.

Example:

Let’s say that you have device AKID= 2021017740 with two serial channels, one for pressure and one for temperature.  

Note that the Channels section (in green) has two attributes, “name” and “units”,  that you defined in ChannelCustomAttributes. These attributes are applied to the two serial channels.  

Likewise, the Attributes section (in red) has two attributes, “name” and “serial.number”, that you defined in DeviceCustomAttributes. These attributes are applied to the device with AKID= 24A14DA825059DBA.  

In both Devices and Channels, you do not need to provide values for all Attributes for every device and channel. 

  2.   Open the appsettings.json file, and then go to either the CSV or the OPC-UA sections: 

In the “Header” and “Line” rows, change the original lines to use the appropriate device and channel custom attributes that you defined in the metadata.json file. 

Change the default “Header” and “Line” rows from: 

"Header": "AKID,ChannelType,ChannelNumber, TimeStamp,Value", 

"Line": ",,,,", 

to:

"Header": "Serial Number, Channel Name, Channel Number, Sampling Time, Value, Units", 

"Line": ",,,,,", 

• We remove the “AKID” and replacing it with the device custom attribute “Serial Number”, which makes it easier to identify each device.  

• We also replaced “ChannelType” with the user-friendly custom attribute “Channel Name”.  
• We added the channel custom attribute “Units” so that Value is clearer to understand.

Stopping, Starting, and Uninstalling Agent 

The Agent is a standard Microsoft Windows service. 

To stop the Agent: 

1. In your desktop, open Windows Services. 

2. In the Services list, right-click FAI.Agent, and then click Stop. 

To start the Agent:  

1. In your desktop, open Windows Services. 

2. In the Services list, right-click FAI.Agent, and then click Start. 

The Agent is launched. The default location of the log file is what you defined in Serilog section of your MQTT Broker configuration file. 

To uninstall the Agent: 

1. In the Search box in the desktop, type Settings.  

2. In the Settings window, click Apps. 

3. Scroll down to FAI.Light, and then click its icon. Click Uninstall. 

Information about Popular MQTT Brokers 

Comparison of MQTT Brokers - Comparison of the seven most popular MQTT Brokers. 

RabbitMQ - Overview, installation, tutorials, CLI tools, configuration, authentication, networking, messages, queues, and other features. 

Mosquitto -  Overview, configuration file, command line interface 

HiveMQ – Introduction, installation, getting started, security, monitoring, logging, and troubleshooting.

Appendix B

CSV parameters in apsettings.json

Return to top

DNP3 parameters in appsettings.json

Return to top

More DNP3 parameters in appsettings.json