—

INSTRUCTION MANUAL

ESI-Manager user application

How to use, change, build and start
—
Table of contents
1 Introduction to this manual............................................................................................................................ 3
1.1 Intended audience .......................................................................................................................................... 3
1.2 Before you start .............................................................................................................................................. 3
1.3 How to use this manual ................................................................................................................................. 3
1.4 Software protocols and physical interface ................................................................................................ 3
2 ESI-Manager communication protocols and physical connections ........................................................ 4
2.1 Overview of communication protocols with the ESI-Manager ............................................................... 4
2.1.1 MODBUS RTU .................................................................................................................................................. 4
2.1.2 MODBUS TCP .................................................................................................................................................. 4
2.1.3 PQ Link protocol............................................................................................................................................. 4
2.2 Overview of physical connections on the ESI-Manager............................................................................ 5
2.2.1 Ethernet / RJ45 .............................................................................................................................................. 5
2.2.2 USB mini .......................................................................................................................................................... 6
2.2.3 USB host connector / USB flash memory key ........................................................................................... 7
3 User Application menu .................................................................................................................................... 8
3.1 User application data and the graphical interface.................................................................................... 8
3.2 How to program the user interface menu .................................................................................................. 9
3.3 User interface menu variables ..................................................................................................................... 11
3.4 Example code ................................................................................................................................................ 14
3.5 Other references ........................................................................................................................................... 16
4 How to build the ESI-Manager User Application ...................................................................................... 17
4.1 User application on a USB key ..................................................................................................................... 17
4.2 Compiling the User application under Linux ............................................................................................. 17
4.3 Compiling the User application under Windows ...................................................................................... 17
5 Access to the ESI-Manager data base ........................................................................................................ 19
5.1 Introduction................................................................................................................................................... 19
5.2 Interface ......................................................................................................................................................... 19
5.2.1 Opening and Closing ................................................................................................................................... 19
5.2.2 Authentication ............................................................................................................................................. 19
5.2.3 Parameter access ........................................................................................................................................ 20
5.2.4 Curve access................................................................................................................................................. 22
5.2.5 Miscellaneous: Reset ................................................................................................................................... 23
5.3 Error codes .................................................................................................................................................... 23
6 Appendices ...................................................................................................................................................... 25
A1 References ........................................................................................................................................................ 25
A3 Description of open ports.............................................................................................................................. 25
A4 Cyber Security Disclaimer note..................................................................................................................... 25

2 Table of contents ç ESI-Manager communication

—
1 Introduction to this manual
1.1 Intended audience
This manual is intended for programmers, commissioning people, supervision people
who need to a specific application, access data, and to develop control software which
will interact with the ESI-Manager and ESI inverters.

1.2 Before you start

This manual describes the User application that will run on the USB host connector of
the ESI-Manager.

To be able to access data of the ESI-Manager and ESI inverters consistently, a basic
knowledge of these products is needed. Functionality of the ESI-Manager, meaning of
various measurements and parameters are some particular aspects that should be
familiar. Look in the ESI-Manager and ESI operating manuals to know more about that.

To be able to program a new application that will run on the ESI, the knowledge of C/C++,
compilation techniques, debugging tools is required.

1.3 How to use this manual

Chapter 2 gives details concerning the ESI-Manager.

Chapter 3 describes the user application menu of the ESI-Manager where the data will
be available and how to build it.

Chapter 4 describes compilation and debug techniques of the user application.

Chapter 5 describes the request commands needed to get data in a user specific
application (stored in a USB key) or through the communication (through USB mini or
Ethernet connectors).

1.4 Software protocols and physical interface

The ESI-Manager supports three communication protocols:

Modbus RTU and Modbus TCP and PQ-Link protocol implementing specific request
commands.

Three physical connections are available:

RS485 with the Modbus Adapter option, USB mini, Ethernet-RJ45 .

The table below resumes the availability of communication protocols depending on the
connection provided.

Available connection
RS485 Modbus USB mini Ethernet-RJ45 USB host
Communication Adapter (option)
protocol Modbus RTU PQ-Link PQ-Link and User specific USB key
Modbus TCP application

ESI-Manager communication ç Table of contents 3

—
2 ESI-Manager communication protocols and
physical connections
2.1 Overview of communication protocols with the ESI-Manager
2.1.1 MODBUS RTU
MODBUS RTU is a non-proprietary serial communications protocol available through the
RS485 Modbus adapter.

2.1.2 MODBUS TCP

MODBUS TCP is a MODBUS RTU message transmitted with a TCP/IP wrapper and sent
over an Ethernet network instead of serial lines. The Server does not have a SlaveID as in
RTU since it uses an IP Address instead.

2.1.3 PQ Link protocol

The PQ Link protocol is a specific way to access the data through specific requests.

These requests can be transmitted to the ESI-Manager through Ethernet / RJ45, USB or
handled directly from the USB key application.

The data can be accessed by different means:

- TCP/IP connection from a local client or from a remote client

- USB device seen as a USB UART interface

- USB memory key where a user specific application is running

The server will allow local and distant access to the ESI-Manager. Different access levels
will be implemented to restrict certain functionality to given users. A login and password
will therefore be required.

The format of the messages transferred via those two medium will be the same.

Two layers will be put on top of them:

This layer is taking care of receiving the frames. The byte stream is
Framing Layer
decoded and frames generated are passed to the layers above.
This is the upper layer taking care of the commands.
Command Layer It will also take care of the authentication of the client during the
connection via some specific commands.

4 Communication protocols and physical connections ç ESI-Manager communication

 Command &
Authentication
Layer

Framing
Layer

TCP/IP
USB

Those two layers will use the same format regardless of the actual “transmission
medium” used.

The data is arranged in packets with integrated error checking.

2.2 Overview of physical connections on the ESI-Manager

2.2.1 Ethernet / RJ45

TCP/IP connections can be indifferently initiated locally or remotely. As the local
connection is used by the UI, it will have extended access rights to parameters compared
to a remote connection.

The TCP port used by default is 4250.

The maximum number of TCP/IP clients to the ESI-Manager is 2.

The connection to the ESI-Manager is an RJ45 Cat5e Ethernet cable

ESI-Manager communication ç Communication protocols and physical connections 5

 The ESI-Manager can be connected directly to a LAN or through Internet

2.2.2 USB mini

The USB interface is used to present the ESI-Manager as a serial interface on its USB
port.

The computer is connected through a USB-A male to USB-Mini B male.

6 Communication protocols and physical connections ç ESI-Manager communication

2.2.3 USB host connector / USB flash memory key
The USB host interface is present on the combo connector (RJ45 + USB-A female).

The user application is present on a USB key that is inserted in the ESI-Manager. This
user application will be launched automatically at boot.

ESI-Manager communication ç Communication protocols and physical connections 7

—
3 User Application menu
3.1 User application data and the graphical interface
The data used by the user application can be display in a user defined menu.

When the USB key is not plugged into the ESI-Manager, the interface is empty.

When a USB key is plugged into the ESI-Manager, the interface will be displayed as
defined into the USB key’s application.

8 User application menu ç ESI-Manager communication

 Selecting a specific row in the list, the user can set the values individually using the
keyboard entry screen.

3.2 How to program the user interface menu

The user application should first store into the ESI-Manager the right menus.

Below are listed the information needed to program the tables. It is possible to
preconfigure

- different applications (Application ID Nr)

- different displays per application (Display ID Nr)

Variable Signification Range

bESIMode Application ID Nr 0, 1, 2,…63
bESIDisplay Display ID Nr 0, 1, 2,…7
bESIMaxMode Max Application ID 1…64
bESIMaxDisplay Max Displayed Screen ID 1…8
bESIMaxDataPerScreen Max Number of Data / Screen 2...12

For instance, in a Peak Shaving application, it is possible to program a few number of

data list corresponding in various functional conditions.

Application example:

Mode: Peak shaving (given by Application ID Nr)

Display: Display ID Nr from 0 to 1, to get 2 different sets of control data

For each Display, a few parameters

ESI-Manager communication ç User application menu 9

 - Maximum P in kW,

- Minimum P in kW,

- Regulation time where it is possible to enter minutes and seconds

Auto adaptation of Max and Min (Enabled or Disabled)

TABLE PEAK SHAVING bytes

Mode M Pk Shaving 1 byte
Set D Set1 1 byte
Max P P1 kW 8 float
Min P P2 kW 8 float
Reg Time Time 1 Min 2 byte
Reg Time Time 2 Sec 2 byte
Auto adapt A Y/N 1 byte
--- --- 0
--- --- 0
Total 23

Than the user has to build the following table:

Name Length Offset

Mode 4 0 byte
--- 3 5 byte
Pk Shaving 10 9 byte
Set 3 20 byte
Set1 4 24 byte
Set2 4 29 byte
Max P 5 34 byte
Min P 5 40 byte
Reg Time 8 46 byte
kW 2 55 byte
Min 3 58 byte
Sec 3 62 byte
Auto adapt 10 66 byte
Y/N 3 77 byte
81 byte
Total 67 byte

10 User application menu ç ESI-Manager communication

3.3 User interface menu variables
- The floating point data are stored into fAppData[16]

0 fAppData [0] Display 0 Display 1

1 fAppData [1] Display 0 Display 1
2 fAppData [2] Display 0 Display 2
3 fAppData [3] Display 0 Display 2
4 fAppData [4] Display 0 Display 3
5 fAppData [5] Display 0 Display 3
6 fAppData [6] Display 0 Display 4
7 fAppData [7] Display 0 Display 4
8 fAppData [8] Display 0 Display 5
9 fAppData [9] Display 0 Display 5
10 fAppData [10] Display 0 Display 6
11 fAppData [11] Display 0 Display 6
12 fAppData [12] Display 0 Display 7
13 fAppData [13] Display 0 Display 7
14 fAppData [14] Display 0 Display 8
15 fAppData [15] Display 0 Display 8

- The byte data are stored into bAppData[64]

16 bAppData[0] Display 0 Display 1

17 bAppData[1] Display 0 Display 1
18 bAppData[2] Display 0 Display 1
19 bAppData[3] Display 0 Display 1
20 bAppData[4] Display 0 Display 1
21 bAppData[5] Display 0 Display 1
22 bAppData[6] Display 0 Display 1
23 bAppData[7] Display 0 Display 1
24 bAppData[8] Display 0 Display 2
25 bAppData[9] Display 0 Display 2
26 bAppData[10] Display 0 Display 2
27 bAppData[11] Display 0 Display 2
28 bAppData[12] Display 0 Display 2
29 bAppData[13] Display 0 Display 2
30 bAppData[14] Display 0 Display 2
31 bAppData[15] Display 0 Display 2
--- ----------- ----- ----
64 bAppData[48] Display 0 Display 7

ESI-Manager communication ç User application menu 11

 65 bAppData[49] Display 0 Display 7
66 bAppData[50] Display 0 Display 7
67 bAppData[51] Display 0 Display 7
68 bAppData[52] Display 0 Display 7
69 bAppData[53] Display 0 Display 7
70 bAppData[54] Display 0 Display 7
71 bAppData[55] Display 0 Display 7
72 bAppData[56] Display 0 Display 8
73 bAppData[57] Display 0 Display 8
74 bAppData[58] Display 0 Display 8
75 bAppData[59] Display 0 Display 8
76 bAppData[60] Display 0 Display 8
77 bAppData[61] Display 0 Display 8
78 bAppData[62] Display 0 Display 8
79 bAppData[63] Display 0 Display 8

- The menus information are stored into a specific 160 bytes structure :

bBESSString[0] bAppDisplayIndex[0] Index of Menu String displayed in row 0 column 0

bBESSString[1] bAppDisplayIndex[1] Index of Menu String displayed in row 1 column 0
bBESSString[2] bAppDisplayIndex[2] Index of Menu String displayed in row 2 column 0
bBESSString[3] bAppDisplayIndex[3] Index of Menu String displayed in row 3 column 0
bBESSString[4] bAppDisplayIndex[4] Index of Menu String displayed in row 4 column 0
bBESSString[5] bAppDisplayIndex[5] Index of Menu String displayed in row 5 column 0
bBESSString[6] bAppDisplayIndex[6] Index of Menu String displayed in row 6 column 0
bBESSString[7] bAppDisplayIndex[7] Index of Menu String displayed in row 7 column 0
bBESSString[8] bAppDisplayIndex[8] Index of Menu String displayed in row 8 column 0
bBESSString[9] bAppDisplayIndex[9] Index of Menu String displayed in row 9 column 0
Index of Menu String displayed in row 10 column
bBESSString[10] bAppDisplayIndex[10] 0
Index of Menu String displayed in row 11 column
bBESSString[11] bAppDisplayIndex[11] 0
bBESSString[12] bAppDataIndex[0] Free
bBESSString[13] bAppDataIndex[1] Free
bBESSString[14] bAppDataIndex[2] Index of Data displayed in row 2 column 1
bBESSString[15] bAppDataIndex[3] Index of Data displayed in row 3 column 1
bBESSString[16] bAppDataIndex[4] Index of Data displayed in row 4 column 1
bBESSString[17] bAppDataIndex[5] Index of Data displayed in row 5 column 1
bBESSString[18] bAppDataIndex[6] Index of Data displayed in row 6 column 1
bBESSString[19] bAppDataIndex[7] Index of Data displayed in row 7 column 1

12 User application menu ç ESI-Manager communication

bBESSString[20] bAppDataIndex[8] Index of Data displayed in row 8 column 1
bBESSString[21] bAppDataIndex[9] Index of Data displayed in row 9 column 1
bBESSString[22] bAppDataIndex[10] Index of Data displayed in row 10 column 1
bBESSString[23] bAppDataIndex[11] Index of Data displayed in row 11 column 1
bBESSString[24] bAppUnitIndex[0] Index of Unit String displayed in row 0 column 2
bBESSString[25] bAppUnitIndex[1] Index of Unit String displayed in row 1 column 2
bBESSString[26] bAppUnitIndex[2] Index of Unit String displayed in row 2 column 2
bBESSString[27] bAppUnitIndex[3] Index of Unit String displayed in row 3 column 2
bBESSString[28] bAppUnitIndex[4] Index of Unit String displayed in row 4 column 2
bBESSString[29] bAppUnitIndex[5] Index of Unit String displayed in row 5 column 2
bBESSString[30] bAppUnitIndex[6] Index of Unit String displayed in row 6 column 2
bBESSString[31] bAppUnitIndex[7] Index of Unit String displayed in row 7 column 2
bBESSString[32] bAppUnitIndex[8] Index of Unit String displayed in row 8 column 2
bBESSString[33] bAppUnitIndex[9] Index of Unit String displayed in row 9 column 2
bBESSString[34] bAppUnitIndex[10] Index of Unit String displayed in row 10 column 2
bBESSString[35] bAppUnitIndex[11] Index of Unit String displayed in row 11 column 2
bBESSString[36] Length String 1 Length
bBESSString[37] String 1 Ascii
bBESSString[38] String 1 ….
bBESSString[39] String 1
bBESSString[40] String 1
bBESSString[41] ….
bBESSString[42] Length String 2 Length
bBESSString[43] String 2 Ascii
bBESSString[44] String 2 ….
bBESSString[45] String 2
bBESSString[46] String 2
bBESSString[47] ….
bBESSString[48] Length String 3 Length
bBESSString[49] String 3 Ascii
bBESSString[50] String 3 ….
bBESSString[51] String 3
bBESSString[52] String 3
bBESSString[53] ….
bBESSString[54] Length String 4
bBESSString[55] String 4
bBESSString[56] String 4
bBESSString[57] String 4
bBESSString[58] String 4

ESI-Manager communication ç User application menu 13

 bBESSString[59] ….
bBESSString[60] ….
bBESSString[61] ….
bBESSString[155] ….
bBESSString[156] ….
bBESSString[157] ….
bBESSString[158] ….
bBESSString[159] ….

3.4 Example code

Below is a short piece of code giving an example how to program the table.
// defines related to BESS applications
#define PEAK_SHAVING 0
#define MAX_MODE 3
#define MAX_DISPLAY_PEAKSHAV 2
#define MAX_DATA_PEAKSHAV 6
// variables related to BESS applications
static unsigned char bAppMode,bAppDisplay,bAppMaxMode,bAppMaxDisplay,bAppMaxDataPerScreen;
static float fAppData[16]; // float variables table
static unsigned char bAppData[64]; // byte variables table
static unsigned char bAppDataIndex[12]; // indexes tables
static unsigned char bAppDisplayIndex[12];
static unsigned char bAppUnitIndex[12];
static unsigned char bAppMenuString[124];

/*****************************************************************/
/** Set Peak Shaving Menu **/
/*****************************************************************/
void SetPeakShavingMenu(unsigned char Screen)
{
unsigned char Index1;

bAppMode = PEAK_SHAVING; // BESS Mode

bAppDisplay = Screen; // BESS Table

if (bAppDisplay >= MAX_DISPLAY_PEAKSHAV) bAppDisplay = MAX_DISPLAY_PEAKSHAV-1;

bAppMaxMode = MAX_MODE; // BESS Mode Max

bAppMaxDisplay = MAX_DISPLAY_PEAKSHAV; // BESS Table Max
bAppMaxDataPerScreen = MAX_DATA_PEAKSHAV; // BESS Data per Table

Index1 = 0;
bAppMenuString[Index1] = 4; // Texts definition
bAppMenuString[++Index1] = 'M'; // give offset and ascii
bAppMenuString[++Index1] = 'o';
bAppMenuString[++Index1] = 'd';
bAppMenuString[++Index1] = 'e';
bAppMenuString[++Index1] = 3;
bAppMenuString[++Index1] = '-';
bAppMenuString[++Index1] = '-';
bAppMenuString[++Index1] = '-';
bAppMenuString[++Index1] = 10;
bAppMenuString[++Index1] = 'P';
bAppMenuString[++Index1] = 'k';
bAppMenuString[++Index1] = ' ';
bAppMenuString[++Index1] = 'S';
bAppMenuString[++Index1] = 'h';
bAppMenuString[++Index1] = 'a';
14 User application menu ç ESI-Manager communication
bAppMenuString[++Index1] = 'v';
bAppMenuString[++Index1] = 'i';
bAppMenuString[++Index1] = 'n';
bAppMenuString[++Index1] = 'g';
bAppMenuString[++Index1] = 3;
bAppMenuString[++Index1] = 'S';
bAppMenuString[++Index1] = 'e';
bAppMenuString[++Index1] = 't';
bAppMenuString[++Index1] = 4;
bAppMenuString[++Index1] = 'S';
bAppMenuString[++Index1] = 'e';
bAppMenuString[++Index1] = 't';
bAppMenuString[++Index1] = '1';
bAppMenuString[++Index1] = 4;
bAppMenuString[++Index1] = 'S';
bAppMenuString[++Index1] = 'e';
bAppMenuString[++Index1] = 't';
bAppMenuString[++Index1] = '2';
bAppMenuString[++Index1] = 5;
bAppMenuString[++Index1] = 'M';
bAppMenuString[++Index1] = 'a';
bAppMenuString[++Index1] = 'x';
bAppMenuString[++Index1] = ' ';
bAppMenuString[++Index1] = 'P';
bAppMenuString[++Index1] = 5;
bAppMenuString[++Index1] = 'M';
bAppMenuString[++Index1] = 'i';
bAppMenuString[++Index1] = 'n';
bAppMenuString[++Index1] = ' ';
bAppMenuString[++Index1] = 'P';
bAppMenuString[++Index1] = 8;
bAppMenuString[++Index1] = 'R';
bAppMenuString[++Index1] = 'e';
bAppMenuString[++Index1] = 'g';
bAppMenuString[++Index1] = ' ';
bAppMenuString[++Index1] = 'T';
bAppMenuString[++Index1] = 'i';
bAppMenuString[++Index1] = 'm';
bAppMenuString[++Index1] = 'e';
bAppMenuString[++Index1] = 2;
bAppMenuString[++Index1] = 'k';
bAppMenuString[++Index1] = 'W';
bAppMenuString[++Index1] = 3;
bAppMenuString[++Index1] = 'M';
bAppMenuString[++Index1] = 'i';
bAppMenuString[++Index1] = 'n';
bAppMenuString[++Index1] = 3;
bAppMenuString[++Index1] = 'S';
bAppMenuString[++Index1] = 'e';
bAppMenuString[++Index1] = 'c';
bAppMenuString[++Index1] = 10;
bAppMenuString[++Index1] = 'A';
bAppMenuString[++Index1] = 'u';
bAppMenuString[++Index1] = 't';
bAppMenuString[++Index1] = 'o';
bAppMenuString[++Index1] = ' ';
bAppMenuString[++Index1] = 'a';
bAppMenuString[++Index1] = 'd';
bAppMenuString[++Index1] = 'a';
bAppMenuString[++Index1] = 'p';
bAppMenuString[++Index1] = 't';
bAppMenuString[++Index1] = 3;
bAppMenuString[++Index1] = 'Y';
bAppMenuString[++Index1] = '/';
bAppMenuString[++Index1] = 'N';

Index1 = 0; // Text offset of ‘Variable’

ESI-Manager communication ç User application menu 15

 bAppDisplayIndex[Index1] = 0; // column in the list
bAppDisplayIndex[++Index1] = 20;
bAppDisplayIndex[++Index1] = 34;
bAppDisplayIndex[++Index1] = 40;
bAppDisplayIndex[++Index1] = 46;
bAppDisplayIndex[++Index1] = 46;
bAppDisplayIndex[++Index1] = 66;

Index1 = 0; // Text offset of ‘Unit’

bAppUnitIndex[Index1] = 9; // column in the list
if (bAppDisplay == 0) bAppUnitIndex[++Index1] = 24;
else bAppUnitIndex[++Index1] = 29;
bAppUnitIndex[++Index1] = 55;
bAppUnitIndex[++Index1] = 55;
bAppUnitIndex[++Index1] = 58;
bAppUnitIndex[++Index1] = 62;
bAppUnitIndex[++Index1] = 77;

Index1 = 2; // Data offset of ‘Value’

bAppDataIndex[Index1] = 0; // column in the list
bAppDataIndex[++Index1] = 1;
bAppDataIndex[++Index1] = 16;
bAppDataIndex[++Index1] = 17;
bAppDataIndex[++Index1] = 18;
}

3.5 Other references

The example is detailed in:

- User Window.xlsx

A project example is included in:

- PRJ-ThirdPartyApp

- PRJ-ThirdPartyApp/src/main.c

This project implements 3 different applications:

- Peak shaving application

- Voltage Control application

- Timer Control application

Please refer to the following documentation to get full information on the data to
handle:

- ESI-Manager communication with Modbus RTU, Modbus TCP and PQ-Link

protocols.pdf

16 User application menu ç ESI-Manager communication

—
4 How to build the ESI-Manager User Application
4.1 User application on a USB key
A user application named « extapp » is automatically launched from a USB key placed in
the USB host connector of the ESI-Manager.

This application should be placed in the root file system of the USB key.

The « extapp » application connects to the ESI data server through the IP address
127.0.0.2.

4.2 Compiling the User application under Linux

The application source code is located in « main.c »

Type « make clean »

Type « make »

The compiled file is named « test »

Rename it as « extapp »

Store it into the USB key and plug the USB key into the ESI-Manager

4.3 Compiling the User application under Windows

Install Cygwin from: http://www.cygwin.com/

During installation, install the following packages:

Install from ‘Devel’

- gcc-core

- gcc-g++

- make

- libiconv

Install from ‘Web’

- wget

Install from ‘Archive’

- unzip

- zip

Install from ‘Net’

- openssh

- openssl

ESI-Manager communication ç How to build the ESI-Manager user application 17

 Run Cygwin

The application source code is located in « main.c »

Type « make clean »

Type « make »

The compiled file is named « test »

Rename it as « extapp »

Store it into the USB key and plug the USB key into the ESI-Manager

18 How to build the ESI-Manager user application ç ESI-Manager communication

—
5 Access to the ESI-Manager data base
5.1 Introduction
This document describes the the basic commands to get access to the whole
parameters and measurements database of the ESI-Manager.

5.2 Interface
5.2.1 Opening and Closing

5.2.1.1 CommandClient_Init
This function opens the connection to the ESI-Manager.

It has the following prototype:

E_Error RVT_command_client_Init( DT_CHAR *ServerAddress,

void (*Callback_ConnectionReset)(void));

The ESI-Manager Address is an IP address.

In the case of an external application running on the USB key, the server addres is fixed
to the IP address 127.0.0.2.

The Callback_ConnectionReset is a pointer to a function that will be called if a loss of

connection with the ESI-Manager is detected.

If one does not wish to use the callback mechanism, this parameter can be set to NULL.
Unwanted disconnections can then be detected when any of the DLL function call
returns the “RVT_SYS_SOCKET_DISCONNECTED” error code.

When a disconnection is happening, it is necessary to call the clean function to free the
PC resources used and try to connect to the ESI-Manager again.

5.2.1.2 CommandClient_Clean
This function closes the connection to the ESI-Manager.

It has the following prototype:

E_Error RVT_command_client_Clean();

The closing allows to free resources allocated.

5.2.2 Authentication
The local administrator user is automatically detected based on its local connection to
the server.

5.2.2.1 CommandClient_Authenticate
This function allows authenticating as a given user on the ESI-Manager.

It has the following prototype:

E_Error RVT_command_client_Authenticate( DT_CHAR *Login,

ESI-Manager communication ç Access to the ESI-Manager database 19

 DT_CHAR *Password,

DT_UINT8 *AccessLevel);

The Login and Password parameters are used to authenticate oneself and the
AccessLevel is returned to indicate the associated access level.

Access levels

The following access levels are defined:

Level Name Description

Very basic user allowing only reading measurements and curves
0x00 Monitor
from the device.
0x10 Configurator More advanced user allowed modifying measurement parameters.
User allowed modifying any parameter of the device and to create
0x40 Administrator
and delete users.
Local Special user created for internal use only. It has the same rights as
0x80
application an Administrator.
0xFF Reserved Reserved.

5.2.2.2 CommandClient_CreateUser
This function allows creating a new user account on the ESI-Manager.

It has the following prototype:

E_Error RVT_command_client_CreateUser ( DT_CHAR *Login,

DT_CHAR *Password,

DT_UINT8 AccessLevel);

The AccessLevel parameter specifies what access level to associate with the new user
account.

5.2.2.3 CommandClient_DeleteUser
This function allows deleting a user account on the ESI-Manager.

It has the following prototype:

E_Error RVT_command_client_DeleteUser (DT_CHAR *Login);

5.2.3 Parameter access

5.2.3.1 CommandClient_GetParameter
This function allows getting a parameter group from the ESI-Manager.

It is restricted to configuration, measurement and information parameters.

The parameter is read from the actual parameters memory.

Note that the parameters that have been set in the shadow memory but not yet applied
are not returned when a “Get Parameter” command is issued.

For a reason of transmission efficiency, it is only possible to transfer parameter by

groups of parameters; in other words, transmission of individual parameters is not
foreseen.

20 Access to the ESI-Manager database ç ESI-Manager communication

 One must have at least Monitor rights to perform this task.

It has the following prototype:

E_Error RVT_command_client_GetParameter( DT_UINT16 ParamGroupID,

DT_UINT8 **Value,

DT_UINT *Size);

The ParamGroupID is specifying which parameter group to get.

The Value and Size parameters are pointers to the buffer where the parameter group
values will be stored and to the actual size of this parameter group.

5.2.3.2 CommandClient_SetParameter
This function allows setting a parameter group in the ESI-Manager.

It is restricted to configuration parameters.

The modification of application specific parameters is applied in a shadow memory.

Parameter changes will only be copied to parameters memory after an “Apply Parameter
Changes” command is issued.

The modification of universal parameters is applied directly i.e. no “Apply Parameter

Changes” command is required.

For a reason of transmission efficiency, it is only possible to transfer parameter by

groups of parameters; in other words, transmission of individual parameters is not
foreseen.

One must have at least Configurator rights to set application specific parameters and
at least administrator rights to set universal parameters.

It has the following prototype:

E_Error RVT_command_client_SetParameter( DT_UINT16 ParamGroupID,

DT_UINT8 *Value,

DT_UINT Size);

The ParamGroupID is specifying which parameter group to set.

The Value parameter is a pointer to the buffer where the data to write is stored and the
Size is specifying the amount of data to be written.

5.2.3.3 CommandClient_ApplyParameterChanges
This function applies the shadowed parameter changes in the parameter memory of the
ESI-Manager.

One must have at least Monitor rights to perform this task.

It has the following prototype:

E_Error RVT_command_client_ApplyParameterChanges();

ESI-Manager communication ç Access to the ESI-Manager database 21

5.2.4 Curve access

5.2.4.1 CommandClient_RequestCurve
It has the following prototype:
E_Error RVT_command_client_RequestCurve(

DT_UINT16 SourceID,

T_CurveCharacteristics *Characteristics);

5.2.4.2 CommandClient_ReleaseCurve
This function is telling the ESI-Manager to stop getting data for the given curve.

If the curve was requested by a single client, the curve is not made available anymore for
the client and the slot is freed.

If the curve was requested by multiple clients, the freeing is only made when the last
client releases the curve.

Note that the effect of this command may not be immediate.

One must have at least Monitor rights to perform this task.

It has the following prototype:

E_Error RVT_command_client_ReleaseCurve(DT_UINT16 SourceID);

5.2.4.3 CommandClient_GetCurve
This function is getting curve data from the ESI-Manager.

It has the following prototype:

E_Error RVT_command_client_GetCurve (DT_UINT16 SourceID,

DT_UINT8 *CurveSetIndex,

DT_UINT16 ChunkIndex,

DT_UNT8 *Value,

DT_UINT *Size);

The SourceID and CurveDescriptor are identifying the curve.

The Value is a buffer where the curve will be stored and the Size is the actual size of the
curve returned. One should make sure that the buffer is big enough to contain the curve.

The curves are transferred by chunks.

This function is taking care of downloading the number of chunks required to get the
complete curve. It is also taking care that all chunks returned do belong to the same
curve set.

One must have at least Monitor rights to perform this task.

5.2.4.4 CommandClient_GetCurveIDs
This function is getting all the SourceIDs currently in use by the DLL.

One must have at least Monitor rights to perform this task.

It has the following prototype:

22 Access to the ESI-Manager database ç ESI-Manager communication
 E_Error RVT_command_client_GetCurveIDs ( DT_UINT16 **Value,

DT_UINT *Size);

The Size is specifying how many SourceIDs have been returned and copied to the
location pointed by the SourceIDs pointer. One must ensure that the location is big
enough to contain the maximum number of curves allowed by the system.

5.2.4.5 CommandClient_GetCurveCharacteristics
This function is getting the characteristics of a given curve.

It has the following prototype:

E_Error RVT_command_client_GetCurveCharacteristics (

DT_UINT16 SourceID,

T_CurveCharacteristics *Characteristics);

This function can be seen as a way to get back the parameters that were passed at the
moment of requesting the curve.

This function along with the GetCurveIDs function allow for an easy re-populating of the
user interface. The interface does not have to store the characteristics of all the curves
it currently manages; it can just ask it back to the ESI-Manager.

One must have at least Monitor rights to perform this task.

5.2.5 Miscellaneous: Reset

This function allows to remotely restarting the ESI-Manager.

It has the following prototype:

E_Error RVT_command_client_Reset();

After calling this command, the connection should be closed using the
CommandClient_Clean function and should be re-established again.

One needs at least Configurator rights to perform this task.

5.3 Error codes

The following error codes can be returned by the DLL:

Error code define Value

RVT_SUCCESS 0
RVT_SYS_MEMORY 1
RVT_SYS_TASK_CREATE 2
RVT_SYS_SEMAPHORE_CREATE 3
RVT_SYS_SEMAPHORE_FAILURE 4
RVT_SYS_PERIPHERAL_IO 5
RVT_MEMORY_CORRUPT 6
RVT_SYS_SOCKET_OPEN 10
RVT_SYS_SOCKET_BIND 11
RVT_SYS_SOCKET_LISTEN 12

ESI-Manager communication ç Access to the ESI-Manager database 23

 RVT_SYS_SOCKET_CONNECT 13
RVT_SYS_SOCKET_DISCONNECTED 14
RVT_SYS_INVALID_OBJECT 16
RVT_SYS_BUFFER_OVERFLOW 17
RVT_SYS_BUFFER_TOO_SMALL 18
RVT_NO_MORE_OBJECT_ALLOWED 20
RVT_OBJECT_NOT_FOUND 21
RVT_OBJECT_OPEN_ERROR 22
RVT_OBJECT_IO_ERROR 23
RVT_NO_MORE_OBJECT 24
RVT_OBJECT_DISABLED 25
RVT_OBJECT_ALREADY_USED 26
RVT_PKT_MALFUNCTION 29
RVT_SECL_UNKNOWN_LOGIN 30
RVT_SECL_INVALID_LOGIN 31
RVT_SECL_LOGIN_FAILURE 32
RVT_SECL_AUTH_FAILURE 33
RVT_SECL_TOO_MANY_USERS 34
RVT_SECL_NOT_LOGGED_IN 35
RVT_SECL_NOT_ENOUGH_RIGHTS 36
RVT_PMDB_INVALID_ID 40
RVT_PMDB_UNAVAILABLE 41
RVT_PMDB_IO_FAILURE 42
RVT_PMDB_INVALID_NVRAM 43
RVT_PMDB_TYPE_MISMATCH 44
RVT_PMDB_OPERATION_DENIED 45
RVT_PMDB_INVALID_SIZE 46
RVT_PMDB_INVALID_CONTENT 47
RVT_FCT_INVALID_PARAMETER 50
RVT_FCT_NEEDS_INITIALIZATION 51
RVT_FCT_OPERATION_FAILED 52
RVT_FCT_OPERATION_DENIED 53
RVT_FCT_OPERATION_TIMEDOUT 54
RVT_FCT_INVALID_RESPONSE 55
RVT_CMD_UNKNOWN 60
RVT_CMD_UNSUPPORTED 61
RVT_CMD_MISMATCH 62
RVT_LOG_SYSLOG_INVALID_ADDR 110
RVT_LOG_OPERATION_DENIED 111

24 Access to the ESI-Manager database ç ESI-Manager communication

—
6 Appendices
A1 References
- RS485 adapter installation and start-up guide

- RS485 adapter user guide

- ESI Installation and Operation Instructions manuals

- User Window.xlsx

- A project example is included in:

· PRJ-ThirdPartyApp

· PRJ-ThirdPartyApp/src/main.c

- 2GCS239013A0070_ESI-Manager communication with Modbus RTU, Modbus TCP

and PQ-Link protocols.pdf

A3 Description of open ports

Port State
502/TCP Open
4250/TCP Open
10022/TCP Open

A4 Cyber Security Disclaimer note

This product is designed to be connected to and to communicate information and data
via a network interface. It is User’s sole responsibility to provide and continuously ensure
a secure connection between the product and User’s network or any other network (as
the case may be). The User shall establish and maintain any appropriate measures (such
as but not limited to the installation of firewalls, application of authentication measures,
encryption of data, installation of anti-virus programs, etc) to protect the product, the
network, its system and the interface against any kind of security breaches,
unauthorized access, interference, intrusion, leakage and/or theft of data or
information.

ABB Ltd and its affiliates are not liable for damages and/or losses related to such
security breaches, any unauthorized access, interference, intrusion, leakage and/or theft
of data or information.

Please note that an ssh account exists for maintenance & development purposes.

ESI-Manager communication ç Appendices 25

— Additional information
s.a. ABB n.v. We reserve the right to make technical changes or
Power Quality Products modify the contents of this document without prior
Avenue Centrale 10 notice. With regard to purchase orders, the agreed
Z.I. Jumet particulars shall prevail. ABB does not accept any
B-6040 Charleroi, Belgium responsibility whatsoever for potential errors or possible
Phone: +32(0) 71 250 811 lack of information in this document.
Fax: +32 (0) 71 344 007 We reserve all rights in this document and in the subject
E-Mail: matter and illustrations contained therein. Any
Marketing: [email protected] reproduction, disclosure to third parties or utilization of
Service: [email protected] its contents – in whole or in parts – is forbidden without
prior written consent of ABB.

http://new.abb.com/high-voltage/capacitors/lv
2GCS241012A0070 – Rev B December 2017

© Copyright 2017 ABB. All rights reserved.