AMAGE PVD

Principle of operation

PVD can operate as a terminal application, but the main idea is to work continuously as a system service. The application loads and registers modules of providers and recipients. When a supplier generates a message, it transmits it to the application core, which distributes it to individual recipients.

Suppliers and customers

Different implementations of providers and recipients are acceptable. The provider is responsible not only for collecting the data, but also for creating the message seed in the form of UUID mappings of the target (a standard setting of the resource parameter in the Amage system) to the collected values. The PVD gets the mapping information from the Amage Sync server with which it is paired. In special situations, such as if pairing is not possible, the mapping data can be entered manually as a mapping.json file. The form of this file will be described in detail later.

The receiver is responsible for handling messages. The standard available receiver is the module responsible for forwarding data to the paired Amage Sync server.

Requirements

PVD’s only absolute requirement is the availability of a Java runtime environment version 8 or later, and enough memory to cache data in case of problems with the free transmission of messages to recipients - a minimum of 512 MB RAM is recommended.

Installation and configuration of applications

Installation of the application consists of unpacking the pvd-all.zip archive in the desired location. The next step is to configure the application and its modules, as described in this chapter.

Configuration files are located in configs directory and subdirectories, all configuration files are saved in JSON format.

Any modification of the application’s configuration requires a restart - only then will the changes made take effect.

Setting the startup directory

At startup, the application uses the user.home system variable to determine the startup directory containing all configuration data and as a storage location for additional data (database for temporary data, logs, etc.).

By default, this directory is set to the user’s directory. To run the application with a different startup directory, start the JVM with the -Duser.home = <directory> option. This will allow you to point to any file storage location.

Catalog structure: * configs - directory with application configurations * consumers - directory with consumer libraries * suppliers - directory with supplier libraries * db - local database directory * logs - directory for application logs and all vendors/consumers

All paths in the documentation refer to the user.home directory. For ease of reference in all data paths, this directory will be labeled <user.home>.

Application configuration

Path to the file: <user.home>/configs/core_config.json The file is optional, if it does not exist (default state), the application will be launched with default settings (described below).

Sample application configuration:

 {
    "suppliersPath":"file:///path/to/suppliers",
    "consumersPath":"file:///path/to/consumers",
    "port":9900,
    "manualNativeLibs":false,
    "debug":false,
    "noRepeat":false,
    "heartbeatTime":-1,
    "cleanupTime": 3600,
    "validityTime": 43200,
    "updateMappingsTime":-1,
    "suppliersDirs": [ "path1", "path2"],
    "suppliersEnabled": [ "s-example"],
    "consumersDirs": [ "path1", "path2"],
    "consumersEnabled": [ "c-example"]
 }

  • suppliersPath - (URL) path to directory with suppliers modules, default directory suppliers.

  • consumersPath - (URL) path to the directory with consumers' modules, default directory consumers.

  • port - (int) port for inter-process communication (RMI), default 9900. Used internally, to send requests to the application instance running in the background (status, shutdown, etc.). There is no need to change this value unless it is in conflict with another service using the port or another PVD instance.

  • debug - (boolean) application debug mode (detailed messages) defaults to false. Causes a large amount of additional information to be logged and therefore should only be used when verifying installations and troubleshooting.

  • noRepeat - (boolean) disable local database, default false. With a very large amount of data, it can significantly improve the efficiency of the application, but prevents the resumption of sending messages that for some reason have not been handled correctly by the recipient.

  • consumerThreads (int) the number of threads used simultaneously by recipients, default 4. Increasing this value may allow you to improve the flow of information at the expense of increasing memory consumption and load on the recipient (e.g. Sync server).

  • manualNativeLibs - (boolean) manually set the needed external libraries, by default false. When this option is disabled, the application will try to load native libraries on its own, which is the recommended behavior. However, you may need to manually load such libraries on unusual system configurations.

  • repeatTime - (long) resume interval, counted in seconds, default 1800 (30 minutes).

  • validityTime - (long) message validity time, calculated in minutes, default 43200 (30 days)

  • cleanupTime - (long) database cleanup time, calculated in seconds, default 3600 (1 hour).

  • repeatLimit - (long) number of messages to be loaded on a single repeat attempt, default 200.

  • heartBeatTime - (long) interval for sending diagnostic (status) information to the paired Sync server, calculated in minutes, default 15 (15 minutes). Setting the value to -1 will disable the sending of diagnostic information.

  • updateMappingsTime - (long) interval for querying the paired Sync server for mapping updates, calculated in minutes, default 15 (15 minutes). Setting the value to -1 will disable querying the server for updates.

  • suppliersDirs - a list of paths to the locations of supplier libraries. Useful when the libraries are located in scattered directories or during development on the source code.

  • suppliersEnabled - a list of enabled vendor modules. Allows to enable only those modules that are expected. If the parameter is absent or empty, all supplier modules are loaded. Here we enter the IDs of the corresponding suppliers.

  • consumersDirs - a list of paths to the location of consumer libraries. Useful when libraries are located in scattered directories or in development on source code.

  • consumersEnabled - a list of enabled consumer modules. Allows to enable only those modules that are expected. If the parameter is absent or empty, all supplier modules are loaded. Here we enter the IDs of the corresponding suppliers.

Module configuration

Unless otherwise set, module files are located in the suppliers and consumers directories by default. Each of these modules is a file with the extension .jar. Disabling a module involves deleting the module file or, better, changing its extension (e.g. from name_modul.jar to name_modul.jar.disabled).

Another option for specifying modules and enabling them is to use suppliersDirs and suppliersEnabled and the same for consumers consumersDirs and consumersEnabled.

The location of the configuration files of each module should follow the pattern: <user.home>/configs/[module type]/[module name]/[module instance name].json, where: * The module type is suppliers in the case of a supplier and consumers in the case of a recipient. * The module name is the internal name of the module (different from the module file name!). * The module instance name module instance name can be anything - the application searches the directory with the module configuration and loads each configuration file as another instance, with a name identical to the file name (omitting the .json extension).

The absence of configuration files for modules that should be loaded will result in an application initialization error. On the other hand, if a configuration file exists, but the corresponding module is disabled/deleted, such a file will simply be ignored.

A detailed description of the configuration of each module is provided later in this manual.

Pairing with Sync/Web Server

Pairing with a Sync/Web server is an optional step, but if it is not done, the application will not send status information and download updated mappings on its own.

Place the assetsync.conf file generated in the Amage Desktop application in the configs directory and restart the application.

Mapping file

In case the PVD application is not paired, it is possible to manually enter the mapping file. The file must be located in <user.home>/configs/mapping.json and have the following structure:

 {
    "version": 0,
    "data": {
        "[klucz_1]": "[UUID_1]",
        "[klucz_2]": "[UUID_2]",
        "[klucz_N]": "[UUID_N]"
    }
 }

The version field can be omitted, in which case it will automatically be set to 0, which is recommended when entering the mapping manually - this will automatically update the mapping to the new version when paired with the Sync server in the future.

A missing data field will be equivalent to no mappings. The value of this field is a comma-separated list of key → UUID pairs.

The mapping file is used to associate the data arising in the supplier modules with the corresponding parameters in the AMAGE system. Parameters in the AMAGE system are identified by their UUID value. Such a list allows you to indicate where a parameter read by suppliers is to be entered in the AMAGE system in the parameter list.
Depending on the configuration of the modules, the mapping file may be optional, as the configuration of the module in question will already specify the linkage of the parameters of the module in question (e.g. MODBUS register) to the corresponding parameter in the system.

Running applications from the command line:

The application can be run from the command line:

java -jar pvd-core.jar

The keyboard shortcut CTRL+C will abort the program. The application should be used as a system service and has been designed as such, but the above method allows you to quickly verify the correct configuration and check its operation.

To change the startup directory, you can use the syntax:

java -Duser.home=<directory> -jar pvd-core.jar

There is a simple startup script for GNU/Linux environment in the application’s root directory.

Installation of system services

The following section describes the steps required to run PVD as a system service, separately for Windows and Linux.

Windows

You need to navigate to the win_service directory using the console/command line.

Note: under some 64-bit systems it may not be possible to use the included prunsrv.exe file. In that case, replace it with the file available in win_service/amd64/prunsrv.exe.

Next, modify the service.bat file by setting all the parameters found in the first part of the configuration. This allows you to change the service name, JVM path, etc.

  • SERVICE_NAME - the name of the service. There cannot be two services with the same name in Windows.

  • SERVICE_CODE - service code used for login systems. Windows login ID.

  • DESCRIPTION - service description

  • CONFIG_HOME - location of the directory with configuration/logs, etc. This allows you to place the configuration directory outside the application installation directory, which in a later stage will allow you to upgrade the application to a newer version without having to store the configuration directory in the same place.

  • LOG_LEVEL - default level of logging details. Options: Error, Info, Warn, Debug

  • JAVA_HOME should point to the directory where Java is installed.

Installation of the service

After modifying the service.bat file, run it with the install argument:

service install
Note: the console (cmd program) must be run with administrator privileges, otherwise the service will not be installed correctly.

You should see a message about the successful installation of the service, from this point on, the service named PVD Application (or whatever you gave it) should be visible in the list of Windows services and ready to run in auto-start mode.

Initialize the service for the first time manually. Note: service center must be started with administrator privileges.

Automatic resumption

To protect against unexpected application shutdown, go to services (services) Windows and find a service with the desired name in the configuration (default PVD Application). Then select settings and in the recovery (recovery) tab set the service to reset itself every time it fails (preferred after 0 min). This will ensure that the application automatically restarts as soon as the problem occurs.

Reinstalling the service

The removal of the PVD application service is analogous to its installation.

Before deleting the service, you need to find it in the System Services view (default name PVD Application). It should be stopped (in the Windows Service Management panel. The next and final step is to execute the following command in the console with administrator privileges:

service remove

You should see a message about the successful removal of the service, from then on the service will not be visible in the list and will not be started during system startup.

The deletion must be performed with administrator privileges. The text console must be run with such privileges.

Linux

To install the services, you need to execute two scripts from the linux_service folder so that the application will start at system startup.

Before installation, complete the pvdapp startup script:

APP_ROOT="/opt/pvd"
JVM_EXE="java"
BIN="pvd-core.jar"
JMX_PORT="9010"
JMX_IP="10.0.0.70"

It is necessary to set: * APP_ROOT - path to the directory with the application. * JVM_EXE - path to Java executable file. * BIN - name of the main jar file with the application * JMX_PORT - port on which you will be able to connect to the JMX for diagnostic purposes. * JMX_IP - IP address on which the JMX service is running.

installmxserver - install moxy server as a service installpvdapp - install applications as a service

sudo ./installmxserver
sudo ./installpvdapp

Using a script named "pvdapp" you can run the program in mode: * start - default mode of operation * stop - stop application operation * restart - restart the application * status - shows the current status of the modules.

Automatic resumption

To protect against unexpected shutdown of the application, run crontab -e from the terminal, and then add to the end of the file:

*/5 * * * * /sciezka/do/pvdapp start

Where instead of 5 you can specify a different value. This is the time interval (in minutes), between attempts to restart the application.

If you have problems, you can change the default text editor such as nano using the command:

export EDITOR=/usr/bin/nano

Available modules and their configuration

This part of the manual describes the available modules, distinguishing which is the supplier and which is the recipient.

Supplier: pvd-supplier-IEC-62056-21

Module name: s-IEC-62056-21.

This module allows reading measurements from IEC-62056-21-compliant electricity meters. The module reads data from serial ports, in at most one thread per port.

Example path to the configuration file: <user.home>/configs/suppliers/s-IEC-62056-21/default.json (another custom name is acceptable instead of default).

 {
    "sleepTime": 30,
    "verboseMode": false,
    "showRawTransmission": false,
    "threadPoolSize":2,
    "sleepBetweenQuerying": 0,
    "disableDelayForUnavailableDevices": false,
    "meterGroupConfigs" : [
        {
            "portName":"/dev/ttyr00",
            "sleepBetweenQuerying": 30,
            "sleepTime": 15,
            "active":true,
            "globalMultipliers":[
            {
                "name":"standard",
                "configs" : {
                    "1.6.0":"{value}*{multiplier}",
                    "1.8.0":"{value}*{multiplier}"
                }
            },
            {
                "name":"pozyton",
                "configs" : {
                    "107":"{value}*{multiplier}",
                    "109":"{value}*{multiplier}"
                }
            }
            ],
            "configs": [
                {
                    "deviceAddress":"51034542",
                    "initialBaudRate": 2400,
                    "timeout": 10000,
                    "active":false,
                    "multiplier":"sqrt(4)/(3^2+2)",
                    "multiplierTemplateName":"standard",
                    "multipliersMap": {
                        "1.6.1":"{value}*12",
                        "1.8.1":"{value}*{multiplier}"
                    }
                },
                {
                    "deviceAddress":"023-0000691",
                    "initialBaudRate": 9600,
                    "timeout": 10000,
                    "meterType": "POZYTON"
                }
            ]
        },
        {
            "portName":"/dev/ttyr02",
            "configs": [
                {
                    "deviceAddress":"51204143",
                    "initialBaudRate": 2400,
                    "timeout": 10000
                },
                {
                    "deviceAddress":"51255055",
                    "initialBaudRate": 2400,
                    "timeout": 10000
                }
            ]
        }
    ]
 }

  • sleepTime - (int) time interval in seconds between downloading data from the counter, default 60s, can be configured globally and then overridden for a given port configuration

  • verboseMode - (boolean) counter mode giving more information, default false.

  • showRawTransmission - (boolean) shows raw data transmission from the counter, default is false

  • threadPoolSize - (int) the maximum size of the thread pool used to read data from the counters. If it is larger than the number of ports, it is truncated to that number.

  • disableDelayForUnavailableDevices - (boolean) disables automatic delay for devices that are not available (e.g. no response). Facilitates diagnostics and connection of such devices, as the system will not delay further readings in case the device does not respond. The default delay is 10 readings.

  • globalMultipliers - (list) containing a unique name (name) as well as a map with the address of the read value to the way the value is to be converted. It must contain {value} → i.e. the read value and optionally {multiplier} i.e. the expression from the given counter.

  • portName - (String) the name of the port on which the counter is located (for Linux these ports are tty, for windows COM, and for moxy ttyr).

  • deviceAddress - (String) the serial number of the device, an address unique to the device through which we can identify it.

  • initialBaudRate - (int) value specific to the counter type, this is the operating frequency specific to the port as well.

  • sleepBetweenQuerying - (int) time interval in seconds between polling of individual counters on a given port.

  • meterType - (String) type of the meter, if it conforms to the standard, the field can be omitted. Available values: STANDARD (default), POZYTON.

  • active - (boolean) whether the port is active, default true, optionally you can disable, in addition when the port is active you can disable the individual counter.

  • multiplier - (String), the multiplier of a given counter. This can be a single value as well as an expression.

  • multiplierTemplateName - (String) the name from the template being used, this must be the name appearing in globalMultipliers in the name field * multipliersMap - (Map) a unique map for the counter with value converters. Must be present {value} otherwise the default value read from the counter is returned. If the same parameter is present in globalMultipliers it is overwritten with this converter.

If the device does not respond (no communication) and this effect occurs for 3 consecutive reading attempts, the system automatically stops trying to communicate with the device for 10 consecutive readings. This allows the system to reduce blocking of communication with other devices on the same bus. After a correct reading, the system automatically resumes reading at the set maximum frequency. We can disable this behavior (e.g. for diagnostic purposes) using the global option disableDelayForUnavailableDevices

Mappings

The key mapped to a UUID is constructed from the serial number of the device, the # character and a standardized code for the value to be read, such as 38547626#1.8.0 (serial number 38547626, value code 1.8.0) or 023-0000691#102.1 (serial number 023-0000691, value code 102.1).

Supplier: pvd-supplier-modbus

**Module name: s-modbus.

This module allows you to read values after the modbus TCP protocol (e.g. from the inverter).

Example path to the configuration file: <user.home>/configs/suppliers/s-modbus/default.json (instead of default another custom name is acceptable, e.g. describing this particular data source).

Version 1 configuration.

Version 1 of the configuration describes communication using basic data types. Preserved for compatibility with existing configurations. Recognized by three parameters in the register definition, e.g. 0:float:100.

 {
      "debug": false,
      "devices":[
            {
                "ip":"192.168.1.104",
                "port":502,
                "sleepTime":10,
                "description":"Falownik Testowy",
                "enabled":"true",
                "useLoHiWordOrder": "false",
                "data": {
                    "0:float:100":"fd005850-86c9-498e-8ab2-d3d7a739daa6",
                    "1:int:0":"2a9ed604-bac9-44b9-84b0-01f91f3b4ee4",
                    "2:float:100":"b063bc0a-06ec-40c8-a5fa-721275443388",
                    "3:float:10":"6028f30e-205a-4fa6-8e9a-0fc4ed11d979",
                    "4:float:10":"46f2b46c-da21-425a-a118-95a8c09b4422",
                    "5:float:10":"38ce3bb2-33b9-49ad-8d85-12eec0020653",
                    "6:int:0":"a2f75e59-96df-4b83-81fe-8e6e96e24330",
                    "7:float:10":"41be100f-ba9a-41a2-bd51-801fc922157f"
                }
            },

            {
                "ip":"192.168.1.105",
                "port":502,
                "sleepTime":10,
                "description":"Falownik Testowy 2",
                "enabled":"false",
                "data": {
                    "0:float:100":"fd005850-86c9-498e-8ab2-d3d7a739daa6",
                    "1:int:0":"2a9ed604-bac9-44b9-84b0-01f91f3b4ee4",
                    "2:float:100":"b063bc0a-06ec-40c8-a5fa-721275443388",
                    "3:float:10":"6028f30e-205a-4fa6-8e9a-0fc4ed11d979",
                    "4:float:10":"46f2b46c-da21-425a-a118-95a8c09b4422",
                    "5:float:10":"38ce3bb2-33b9-49ad-8d85-12eec0020653",
                    "6:int:0":"a2f75e59-96df-4b83-81fe-8e6e96e24330",
                    "7:float:10":"41be100f-ba9a-41a2-bd51-801fc922157f"
                }
            }

        ]
}

Version 2 configuration.

Version 2 of the configuration describes communication using all known MODBUS data types. It tries to handle all data types.

 {
      "debug": false,
      "devices":[
            {
                "ip":"192.168.1.104",
                "port":502,
                "unitId":1,
                "addressShift":-1,
                "sleepTime":10,
                "useLoHiWordOrder": "false",
                "description":"Falownik Testowy",
                "enabled":"true",
                "data": {
                    "40072:uint32:Power Active:2": "b2ddc792-cf40-42b7-b9ce-82eb68928ac3",
                    "40005:string32:Manufacturer:0": "c2ddc792-cf40-42b7-b9ce-82eb68928ac3"
                }
            }

        ]
 }

Definition data:

  • debug - (boolean) flag enabled allows logging in logs/console information from the communication library and displaying data sent and received in HEX format

General data contains information about individual devices.

  • ip - (String) ip address of the device.

  • port - (int) port on which we will connect (standard 502).

  • unitId - (int) modbus unit number (usually 1).

  • addressShift - (int) address shift, e.g. -1. Applied always in case of reading. Allows definition in mapping the actual addresses from the documentation and at the same time the appropriate shift according to the protocol of the device. <Option>.

  • addressBase - (int) base value of the address. Always added to the address. <Option>.

  • description - (String) description of the device.

  • When reading a DWORD (two registers), by default we use HiLo register alignment, that is, the highest byte first and then down to the lowest byte. With this option enabled, we use the reverse alignment BUT only for registers. That is, if we read bytes from TWO registers [A] [B] [C] [D] the HiLo alignment will be MSB [A] [B] [C] [D] LSB, while for LoHi alignment it will be MSB [C] [D] [A] [B] LSB.

  • sleepTime - (int) time interval in seconds to read the protocol.

  • enabled - (boolean) flag whether we want to read the device.

  • data - (Map<String, UUID>) Map of the registers we are going to read, and the UUID under which they are to be cast.

Register map format, contains a pair of register configuration and UUID of parameter settings.

Version 1 configuration.

The registry configuration consists of three fields:

  • register number (e.g., 2003)

  • data type - int or float

  • divisor - determines by what number the reading will be divided, for example, for a reading of register 1000 with the value 1234 of float type and divisor 100 we get the result 12.34

Version 2 configuration.

The register configuration consists of 4 fields:

  • register number (e.g., 2003)

  • typ danych - uint16, uint32, uint64, int16, int32, bitfield16, enum16, acc32, float32, string32, string16

  • description - description for the user (appears in the logs)

  • divisor - determines by what number the reading will be divided, for example, for a reading of register 1000 with the value 1234 of float type and divisor 100 we get the result 12.34. We always use 2 characters after the decimal point

Supplier: pvd-supplier-modbus-rtu

**Module name: s-modbus-rtu.

This module allows you to read values from devices after the modbus RTU protocol, that is, the MODBUS protocol over serial buses of the RS-232/RS-485 type. In the documentation, we omit the mechanism of physical connection of the RS device/converter to a given system, on which the PVD application is installed.

Intermediary devices such as Moxa N-Port (or similar) can also be used for connections. In this case, there is usually additional utility software from the respective manufacturer to make the serial ports of the device available as virtual serial ports whether in a Windows or Linux environment. Refer to the manufacturer’s documentation to connect/map the appropriate ports.

Example path to the configuration file: <user.home>/configs/suppliers/s-modbus-rtu/default.json (instead of default another custom name is acceptable, e.g. describing this particular data source). There can be any number of such configurations, e.g., broken down by individual serial ports.

Configuration.

The configuration is divided into a data tree. Physical devices (communication units) are grouped into communication (serial) ports with the same communication parameters. That is, we have a hierarchy of general configuration → ports → devices.

An example configuration file is provided below. It contains the definition of one serial port and one device connected to this port.

 {
    "sleepTime": 30,
    "debug": false,
    "threadPoolSize": 1,
    "sleepBetweenQuerying": 2,
    "disableDelayForUnavailableDevices": false,
    "ports": [
        {
            "sleepTime": 3,
            "sleepBetweenQuerying": 1,
            "active": true,
            "port": "/dev/ttyUSB0",
            "baudRate": 9600,
            "dataBits": 8,
            "stopBits": 1,
            "parity": "None",

            "devices": [
                {
                    "name": "Test modbus RTU device",
                    "description": "additional description for the device",
                    "active": true,
                    "unitId": 1,
                    "addressShift": 0,
                    "addressBase": 0,
                    "useLoHiWordOrder": true,
                    "sleepTime": 5,
                    "data": {
                        "0:float32:Current Voltage - clamp A:0": "97c95bd0-abe4-4770-bdef-23b6f075cd0f",
                        "2:float32:Current Voltage - clamp B:100": "97d95bd0-abe4-4770-bdef-23b6f075cd0f"
                    }
                }
            ]
        }
    ]
 }
It was assumed that one serial port has its definitions, i.e. bit rate, communication parameters uniform for all devices connected to this port. This is due to the characteristics of the data link. Different speeds/parameters can cause erroneous operation of devices pinned on the same bus.

General definition data:

  • sleepTime - (int) time interval in seconds between downloading data from the device, default 60s, can be configured globally and then overridden for a given port configuration

  • debug - (boolean) flag enabled allows logging in logs/console information from the communication library and displaying data sent and received in HEX format

  • threadPoolSize - (int) the maximum thread pool size used to read data from devices. If it is larger than the number of ports, it is truncated to that number.

  • sleepBetweenQuerying - (int) time interval in seconds between polling of individual devices on a given port. It can be overridden on individual ports.

  • disableDelayForUnavailableDevices - (boolean) disables automatic delay for devices that are not available (e.g. no response). Facilitates diagnostics and connection of such devices, as the system will not delay further readings in case the device does not respond. The default delay is 10 readings.

Serial port data:

  • sleepTime - (int) time interval in seconds between downloading data from the device,

  • sleepBetweenQuerying - (int) time interval in seconds between polling of individual devices on a given port.

  • active - whether the port is active and we read data from it

  • port - port name, e.g. COM1, /dev/ttyUSB0, etc.

  • baudRate - bit rate, e.g. 9600

  • dataBits - number of data bits - 7/8

  • stopBits - number of stop bits - 0/1

  • parity - evenness of communication - values: Even, Mark, None, Odd, Space

Data of the individual device:

  • name - (String) device name (appears in logs).

  • description - (String) device description - descriptive field for configuration.

  • active - (boolean) flag whether we want to read the device.

  • unitId - (int) modbus unit number (usually 1).

  • addressShift - (int) address shift, e.g. -1. Applied always in case of reading. Allows definition in mapping the actual addresses from the documentation and at the same time the appropriate shift according to the protocol of the device. <Option>.

  • addressBase - (int) base value of the address. Always added to the address. <Option>.

  • When reading a DWORD (two registers), by default we use HiLo register alignment, that is, the highest byte first and then down to the lowest byte. With this option enabled, we use the reverse alignment BUT only for registers. That is, if we read bytes from TWO registers [A] [B] [C] [D] the HiLo alignment will be MSB [A] [B] [C] [D] LSB, while for LoHi alignment it will be MSB [C] [D] [A] [B] LSB.

  • sleepTime - (int) time interval in seconds to read the protocol.

  • data - (Map<String, UUID>) Map of the registers we are going to read, and the UUID under which they are to be cast.

The format of the register map, contains a pair of register configurations and UUID of the parameter settings are in accordance with version 2 of the Modbus TCP configuration, ie.

Version (2) configuration.

The register configuration consists of 4 fields:

  • register number (e.g., 2003)

  • typ danych - uint16, uint32, uint64, int16, int32, bitfield16, enum16, acc32, float32, string32, string16

  • description - description for the user (appears in the logs)

  • divisor - determines by what number the reading will be divided, for example, for a reading of register 1000 with the value 1234 of float type and divisor 100 we get the result 12.34. We always use 2 characters after the decimal point

If the device does not respond (no communication) and this effect occurs for 3 consecutive reading attempts, the system automatically stops trying to communicate with the device for 10 consecutive readings. This allows the system to reduce blocking of communication with other devices on the same bus. After a correct reading, the system automatically resumes reading at the set maximum frequency. We can disable this behavior (e.g. for diagnostic purposes) using the global option disableDelayForUnavailableDevices

Supplier: pvd-file-content-reader

Module name: s-file-content.

This module allows periodic reading of values from a file. It allows, for example, to read data stored in the /proc system or in other files, e.g. parameter values of 1-Wire sensors using the file system view.

Example path to the configuration file: <user.home>/configs/suppliers/s-file-content/default.json (instead of default another custom name is acceptable, e.g. describing this particular data source).

 {
  "pathFile":"/path/to/file",
  "sleepTime":10,
  "uuid":"f01ec5fd-117c-4cbf-aed8-1ab6066bd4c7",
  "charsetName":"UTF-8"
 }

  • pathFile - (path) path to the file from which we want to read data.

  • sleepTime - (int) time interval in seconds to read from the file.

  • uuid - (uuid) unique parameter uuid number for this file. (same as in the application).

  • charsetName - (String) optional choice of encoding, default UTF-8.

Recipient: pvd-consumer-params-rest

**Module name: c-params-rest.

This module allows you to forward messages to the selected Sync server.

Example path to the configuration file: <user.home>/configs/consumers/c-params-rest/default.json. (Instead of default, another custom name is acceptable, e.g. describing the recipient).

 {
    "connectionTimeout": 5,
    "skipTime": 180,
    "restConfig": {
        "apiKey": "666f6f",
        "apiSecret": "626172",
        "protocol": "http",
        "host": "localhost",
        "context": "",
        "port": 5000,
        "deviceUUID": "26f4c3a7-3820-4d0f-844e-134da324a40b"
    }
 }
----

  • connectionTimeout - (int) time (in seconds) after which the connection will be considered failed, default 5. Prevents the output from blocking.

  • skipTime - (int) the time (in seconds) that must pass after a failed connection before a retry is made, default is 180. Prevents the output from blocking.

The value of the restConfig field indicates the configuration of the connection to the Sync server. If it is the same server with which the application was paired, just insert the configuration from the assetsync.conf file here.

  • apiKey - (String) apiKey of the device

  • apiSecret - (String) apiSecret of the device

  • protocol - (String) type of protocol used to send data

  • host - (String) assetsync server address

  • context - (String) assetsync server context

  • port - (int) port number used to communicate with assetsync

  • deviceUUID - (uuid) unique uuid of the device

Supplier: pvd-supplier-test

**Module name: s-example.

Generates random data at intervals.

Example path to the configuration file: <user.home>/configs/suppliers/s-example/default.json. (Instead of default, another custom name is acceptable).

All fields are optional.

 {
    "threadPoolSize": 1,
    "generatorsQuantity": 1,
    "sleepTime": 1000,
    "payloadSize": 1,
    "parameterUUID": "ef466d4f-ec72-44c5-939c-287e7646b125"
 }

  • threadPoolSize - (int) number of threads used to generate the value, default is 1.

  • generatorsQuantity - (int) number of generators.

  • sleepTime - (int) time (in milliseconds) how often to query the generator for a value.

  • payloadSize - (int) number of generated values.

  • parameterUUID - (UUID) parameter to which the generated value applies

Recipient: pvd-consumer-test

**Module name: c-example.

Logs all received messages, does not forward them.

Example path to the configuration file: <user.home>/configs/consumers/c-example/default.json. (Instead of default, another custom name is acceptable).

This module does not allow configuration, the configuration file always looks the same:

{}

Supplier: pvd-supplier-DLMS

**Module Name: s-DLMS.

The DLMS provider allows communication with devices using the DLMS protocol. Configuring the provider involves specifying access parameters for the devices and a list of OBIS codes that will be read from the devices.

 {
    "sleepTime": 30,
    "threadPoolSize":2,
    "obisCodes": ["1.1.2.6.0.255"],
    "meterGroupConfigs" : [
        {
            "portName":"/dev/ttyUSB0",

            "configs" : [
                {
                    "deviceAddress":"9569",
                    "initialBaudRate": 9600,
                    "timeout": 10000,
                    "logicalId":1,
                    "clientId":16
                }
            ]
        }
    ]
 }

  • threadPoolSize - (int) number of threads used to generate the value, default is 1.

  • obisCodes - (list) list of OBIS codes that will be read from devices

  • meterGroupConfig - (struct) meter configuration structure

  • deviceAddress - (string) device serial number

  • logicalId - (int) logical ID of the device within the communication

  • clientId (int) ID of the access client

Mapping to parameters implemented using sync mapping configuration.

Supplier: pvd-supplier-sql

Module name: s-sql.

Mechanism for retrieving data from an external source in the form of a table with measurements. Provider definition implemented using a sample configuration with access to MS SQL server:

 {
    "dbDriver":"com.microsoft.sqlserver.jdbc.SQLServerDriver",
    "dbUrl":"jdbc:sqlserver://100.100.100.100\\INSTANCE:1433;databaseName=database;",
    "dbUser":"amage",
    "dbPassword":"amage",
    "tableName":"POMIARY",
    "timeBetweenDispatch": 120
 }

  • dbDriver - JDBC driver class for access. MS SQL server and PostgreSQL available.

  • dbUrl - URL in JDBC format to access the database

  • dbUser - user to authorize access

  • dbPassword - user password for access authorization

  • tableName - name of the source table from which we retrieve data

  • timeBetweenDispatch - time between scans of the source table in seconds.

The columns in the source table must have the following structure:

  • DateTime - date - reading date

  • TagName - string - parameter name

  • Value - string - parameter value

After reading, the entire contents of the measurement table are deleted (in a given session).

Mapping to parameters implemented using sync mapping configuration.

Recipient: pvd-consumer-params-sql

Module name: c-params-sql.

Receives parameter data from the Sync system and passes it to external tables with a fixed structure.

The columns in the source table must have the following structure:

  • [1] - date - reading date

  • [2] - string - parameter name

  • [3] - string - parameter value

Example configuration file:

 {
    "dbDriver":"com.microsoft.sqlserver.jdbc.SQLServerDriver",
    "dbUrl":"jdbc:sqlserver://100.100.100.100\\INSTANCE:1433;databaseName=database;",
    "dbUser":"amage",
    "dbPassword":"amage",

    "targetParams": [
        {
            "valueName":"00MKA10CE901",
            "uuid":"37073696-74cf-4a40-847f-bae4a2debedc",
            "multiplier":1
        },
        {
            "valueName":"00AEA00CE902",
            "uuid":"65a56440-018b-4ddd-b1f9-ae6cce642e31",
            "multiplier":1
        },
        {
            "valueName":"00AEA00CE901",
            "uuid":"ee6e896d-a0ab-4932-8635-5f25e6e9ef63",
            "multiplier":1
        }

    ],

    "table" : [
        {
            "tableName":"dbo.Liczniki_E_01M",
            "time":60
        },
        {
            "tableName":"dbo.Liczniki_E_15M",
            "time":900
        }
    ]
 }

  • dbDriver - JDBC driver class for access. MS SQL server and PostgreSQL available.

  • dbUrl - URL in JDBC format to access the database

  • dbUser - user to authorize access

  • dbPassword - user password for access authorization

  • targetParams - target parameters for export

  • table - tables to which data will be exported

  • valueName - name of the target parameter to be entered into the target table

  • uuid - UUID of parameter settings in the AMAGE system for export to an external system

  • multiplier - multiplier to perform in the case of numerical data

  • tableName - name of the table to be exported

  • time - data sending period

This approach allows exporting data at different times to different tables.

Recipient: pvd-failure

**Module name: c-failure.

A test data receiver that on receiving any message generates a DispatchResult.FAILURE response.

Supplier: pvd-supplier-huawei-pv-rest

**Module name: s-huawei-pv-rest.

A mechanism for downloading data on inverters used in photovoltaic systems. Communication takes place via an HTTP REST interface to an external server from Huawei (at the time of writing the documentation servers in the domain fusionsolar.huawei.com). This means that the application must have access to the aforementioned address and descendant addresses in this domain to allow access to this data.

 {
    "devices": [
        {
            "description": "Huawei PV - SUN2000-15KTL-M0 - SN: 123",
            "userName": "user",
            "systemCode": "systemcode",
            "stationCode": "xxx",
            "deviceId": 0,
            "deviceTypeId": 0,
            "sleepTime": 10,
             "data": {
                 "grid_frequency:Grid frequency:0": "d119b575-0604-4404-b954-017a828fe98d"
             },
            "enabled": true
        }
    ]
 }

  • description - Description of the device

  • userName - user to log in to the REST system

  • systemCode - system code for logging into the REST system

  • stationCode - station identifier

  • deviceId - device number

  • deviceTypeId - device type

  • sleepTime - the time of breaks between readings (seconds)

  • enabled - enable/disable configuration

  • data - parameter mapping data to UUID of parameter settings

The configuration skeleton can be generated directly in the AMAGE application for a given device. In the context menu of the resource there are actions for generating the skeleton file.

After creating the aforementioned backbone file, you can proceed to further configuration. The most important thing is to have userName/systemCode data obtained from Huawei system implementers (or directly from Huawei Solar). We enter this data into the configuration.

If you don’t know the station ID, device ID or device type, leaving the default values of "xxx" or 0, the system at startup will display all available data from which you can copy this information. This information can also be copied from Huawei’s data access web interface.

After filling in all the data, the parameter settings mappings should be configured accordingly. It consists of three segments:

<function number>:<name>:<scaling>

Where:

  • Function number is the name of the function from the dictionary below. Corresponds to parameters readable by devices

  • Name - auxiliary parameter, displayed in PVD logs and from the parameter configuration in the AMAGE application

  • Scaling - 0 → no scaling. If > 0, the measured value will be DIVIDED into the given value. This allows, for example, reading data in kWh and converting it to MWh immediately before sending it to the main system.

Recipient: pvd-consumer-csv

**Module name: c-csv.

The module allows you to save data locally in the PVD application runtime environment. Data is received by standard methods from data providers and then saved in a CSV format file (semicolon separator ;) in the destination directory. When the separateFiles option is enabled to true, the system saves the messages in separate files for each UUID after receiving them.

In the case of separateFiles = false, a file named output.csv is created in the destination directory and values in the format are written to it:

  • Timestamp (ISO)

  • Parameter UUID

  • Read parameter value

e.g.

2022-05-12T13:10:44.888;b89da96b-d444-4adc-93b7-b9b7e0798c12;11341;

In the case of separateFiles = true separate files are created. For the aforementioned case, a file named b89da96b-d444-4adc-93b7-b9b7e0798c12.csv and sample content (one record) will be created in the target directory:

2022-05-12T13:10:44.888;11341;

Files are completed, i.e. if they exist and are not empty then the values will be added to the end of the file

Configuration example:

 {
    "resultPath": "/home/user/result_folder",
    "separateFiles": true
 }