2GCS213014A0050 - RVT Communication Through Modbus, USB or TCPIP Protocol
2GCS213014A0050 - RVT Communication Through Modbus, USB or TCPIP Protocol
2GCS213014A0050 - RVT Communication Through Modbus, USB or TCPIP Protocol
All information available from the keyboard of the RVT will be available through the data
table. Addresses, access levels and protocol information are of concerns.
IT
To be able to access data of the Power Power Factor Controller RVT consistently, a
basic knowledge of it is needed. Functionality of the RVT, meaning of various
measurements, logging of data are some particular aspects that should be familiar. Look
in the RVT operating manual to know more about it.
Chapter 3 describes Modbus functions and how Modbus is implemented in the controller.
Chapter 4 describes USB / TCP/IP protocol and how it is implemented in the controller.
Chapter 5 contains the table reference and formats to access measurements / settings
data.
Chapter 6 describes the Windows DLL to handle USB / TCP/IP requests in a user
specific application.
2.1 Overview
MODBUS RTU is a non-proprietary serial communications protocol that is widely used in
the process control industry. The protocol was developed by Modicon for PLC
communications and later released for public use.
This protocol is available in all major Human Machine Interface (HMI) software packages
and terminals. Many of the major controller and PLC manufacturers also offer MODBUS
protocol as a standard or optional protocol in their instrumentation.
The hardware over which MODBUS RTU communications are performed is not defined
by the protocol. MODBUS RTU is supported on RS-232, RS-422, RS-485, Ethernet and
other electrical standards. It should be noted that MODBUS RTU, MODBUS ASCII and
MODBUS Plus are unique communication formats, and are not compatible with each
other. This document will discuss MODBUS RTU only.
The RS485 Modbus Adapter is an option to the RVT. It enables the connection of the
RVT controller to an RS485 Modbus network.
RVT communication through Modbus, USB or TCP/IP protocol Modbus protocol overview - 5
CAUTION: Be careful that the RS485 MODBUS ADAPTER is the one with a GREEN text
colour (3.3V power supply). The one with a WHITE text colour is reserved for the old
model (5V power supply).
6 – Modbus protocol overview RVT communication through Modbus, USB or TCP/IP protocol
2.3 Transactions on Modbus Networks
Modbus protocol uses a master–slave technique, in which only one device (the master)
can initiate transactions (called ‘queries’). The other devices (the slaves) respond by
supplying the requested data to the master, or by taking the action requested in the
query. Typical master devices include host processors and programming panels. Typical
slaves include programmable controllers.
The master can address individual slaves, or can initiate a broadcast message to all
slaves.
Slaves return a message (called a ‘response’) to queries that are addressed to them
individually. Responses are not returned to broadcast queries from the master.
The Modbus protocol establishes the format for the master’s query by placing into it the
device (or broadcast) address, a function code defining the requested action, any data to
be sent, and an error–checking field. The slave’s response message is also constructed
using Modbus protocol. It contains fields confirming the action taken, any data to be
returned, and an error–checking field. If an error occurred in receipt of the message, or if
the slave is unable to perform the requested action, the slave will construct an error
message and send it as its response.
The Query:
The function code in the query tells the addressed slave device what kind of action to
perform. The data bytes contain any additional information that the slave will need to
perform the function.
The data field must contain the information telling the slave which register to start at and
how many registers to read.
The error check field provides a method for the slave to validate the integrity of the
message contents.
The Response:
If the slave makes a normal response, the function code in the response is an echo of the
function code in the query. The data bytes contain the data collected by the slave, such
as register values or status. If an error occurs, the function code is modified to indicate
RVT communication through Modbus, USB or TCP/IP protocol Modbus protocol overview - 7
that the response is an error response, and the data bytes contain a code that describes
the error.
The error check field allows the master to confirm that the message contents are valid.
Only RTU mode will be used here. The mode and serial parameters must be the same for
all devices on a Modbus network.
RTU Mode
The main advantage of this mode is that its greater character density allows better data
throughput than ASCII for the same baud rate.
1 start bit
The messages are transmitted in the network from left to right, i.e. the Least
Significant Bit (LSB) first and the Most Significant Bit (MSB) last.
RTU Framing
In RTU mode, messages start with a silent interval of at least 3.5 character times.
8 – Modbus protocol overview RVT communication through Modbus, USB or TCP/IP protocol
This is most easily implemented as a multiple of character times at the baud rate that is
being used on the network (shown as T1–T2–T3–T4 in the figure below).
Another factor to consider is that each device has its own response time. This response
time can be anywhere from a few milliseconds to a few hundred milliseconds. The Host
must be configured to allow adequate time for the slowest device to respond.
Networked devices monitor the network bus continuously, including during the ‘silent’
intervals. When the first field (the address field) is received, each device decodes it to find
out if it is the addressed device.
Following the last transmitted character, a similar interval of at least 3.5 character times
marks the end of the message. A new message can begin after this interval.
The entire message frame must be transmitted as a continuous stream. If a silent interval
of more than 1.5 character times occurs before completion of the frame, the receiving
device flushes the incomplete message and assumes that the next byte will be the
address field of a new message.
Similarly, if a new message begins earlier than 3.5 character times following a previous
message, the receiving device will consider it is a continuation of the previous message.
This will set an error, as the value in the final CRC field will not be valid for the combined
messages. A typical message frame is shown below.
For a complete description of the Modbus protocol, please look at the Modicon
RVT communication through Modbus, USB or TCP/IP protocol Modbus protocol overview - 9
3 Modbus function codes
For example:
The coil known as ‘coil 1’ in a programmable controller is addressed as coil 0000 in the
data address field of a Modbus message.
Holding register 40001 is addressed as register 0000 in the data address field of the
message.
The function code field already specifies a ‘holding register’ operation. Therefore the
‘4XXXX’ reference is implicit.
10 – Modbus function codes RVT communication through Modbus, USB or TCP/IP protocol
3.2 Supported function codes
The following table gives the Modbus functions which are implemented and supported.
The code is the one used in function field of the Modbus message.
The address space concerned and the purpose of the function are given below.
Remark: please note that for security reasons broadcast is not supported by the RVT.
If the slave device receives the query without a communication error, and can
handle the query normally, it returns a normal response.
If the slave does not receive the query due to a communication error, no
response is returned. The master program will eventually process a timeout
condition for the query.
If the slave receives the query, but detects a communication error (parity or
CRC), no response is returned. The master program will eventually process a
timeout condition for the query.
If the slave receives the query without a communication error, but cannot handle
it (for example, if the request is to read a non–existent coil or register), the slave
will return an exception response informing the master of the nature of the error.
RVT communication through Modbus, USB or TCP/IP protocol Modbus function codes - 11
3.4 Reads and writes to Modbus addresses (functions 1, 2, 3, 4, 5, 6, 15, 16, 22, 23)
The format of a read function (read coil status (01), read input status (02), read input
registers (04), read holding registers (03)) is as follows:
QUERY RESPONSE
Slave address 1 byte Slave address 1 byte (echo of master's query)
Function 1 byte Function 1 byte (echo of master's query)
Starting data address 2 bytes Byte count 1 byte
Quantity of points 2 bytes Data values N bytes
Error check field CRC 2 bytes Error check field CRC 2 bytes
The format of a force single coil (05) or a preset single register (06) function is as follows:
QUERY RESPONSE
Slave address 1 byte Slave address 1 byte (echo of master's query)
Function 1 byte Function 1 byte (echo of master's query)
Data address 2 bytes Data address 2 bytes
Data value 2 bytes Data value 2 bytes
Error check field CRC 2 bytes Error check field CRC 2 bytes
The format of a force multiple coil (15) or a preset multiple registers (16) function is as
follows:
QUERY RESPONSE
Slave address 1 byte Slave address 1 byte (echo of master's query)
Function 1 byte Function 1 byte (echo of master's query)
Data address 2 bytes Data address 2 bytes
Quantity of points 2 bytes Quantity of points 2 bytes
Byte count 1 byte Error check field CRC 2 bytes
Data values N bytes
Error check field CRC 2 bytes
QUERY RESPONSE
Slave address 1 byte Slave address 1 byte (echo of master's query)
Function 1 byte Function 1 byte (echo of master's query)
Read data address 2 bytes Byte count 1 byte
Read quantity of points 2 bytes Data values N bytes
Write data address 2 bytes Error check field CRC 2 bytes
Write quantity of points 2 bytes
Byte count 1 byte
Write data values N bytes
Error check field CRC 2 bytes
QUERY RESPONSE
Slave address 1 byte Slave address 1 byte (echo of master's query)
Function 1 byte Function 1 byte (echo of master's query)
Data address 2 bytes Data address 2 bytes
And mask 2 bytes And mask 2 bytes
Or mask 2 bytes Or mask 2 bytes
Error check field CRC 2 bytes Error check field CRC 2 bytes
12 – Modbus function codes RVT communication through Modbus, USB or TCP/IP protocol
3.5 Fetch comm event counter (function 11)
The controller’s event counter is incremented once for each successful message
completion. It is not incremented for exception responses, poll commands, or fetch event
counter commands. It returns amount of successful read/write operations on data points.
The format of a Fetch comm event counter (11) function query is as follows:
QUERY RESPONSE
Slave address 1 byte Slave address 1 byte (echo of master's query)
Function 1 byte Function 1 byte (echo of master's query)
Error check field CRC 2 bytes Status word 2 bytes (0)
Event counter 2 bytes
Error check field CRC 2 bytes
The format of a Fetch comm event log (12) function query is as follows:
QUERY RESPONSE
Slave address 1 byte Slave address 1 byte (echo of master's query)
Function 1 byte Function 1 byte (echo of master's query)
Error check field CRC 2 bytes Byte count 1 byte
Status word 2 bytes (0)
Event counter 2 bytes
Bus message counter 2 bytes
Event log buffer N bytes
Error check field CRC 2 bytes
The 64 bytes wide Event log buffer is filled with communication events. The most recent
communications event is shown in the Event 0 byte.
Event bytes are stored in the Even log buffer for 4 different reasons.
The bit will be set to logic ‘1’ if the corresponding condition is TRUE.
This type of event byte is stored by the slave when a query message is received.
Bit Contents
0 Not Used
1 Communications Error
2 Not Used
3 Not Used
4 Character Overrun
6 Broadcast Received
7 1
RVT communication through Modbus, USB or TCP/IP protocol Modbus function codes - 13
Slave Modbus Send Event
This type of event byte is stored by the slave when it finishes processing a query
message.
Bit Contents
2 Not used
3 Not used
6 1
7 0
This type of event byte is stored by the slave when it enters the Listen Only Mode.
This type of event byte is stored by the slave when its communications port is restarted.
The slave can be restarted by the Diagnostics function (code 08), with subfunction
Restart Communications Option (code 01).
QUERY
Slave address 1 byte
Function 1 byte
Subfunction 2 bytes
Data field 2 bytes
Error check field CRC 2 bytes
The format of a response to a diagnostics function query is an echo of the query itself.
If the request is directed to a counter, however, the slave returns the counter’s value in
the data field.
The data in the query data field is to be returned (looped back) in the response. The
entire response should be identical to the query.
The slave’s peripheral port is to be initialized and restarted, and all of its communication
event counters are to be cleared. If the port is currently in the Listen Only Mode, no
response will be sent. If the port is not currently in the Listen Only Mode, a normal
response will be sent. This occurs before the restart is executed.
14 – Modbus function codes RVT communication through Modbus, USB or TCP/IP protocol
02 Return Diagnostic Register (Not supported)
03 (Not supported)
Forces the addressed slave to enter the Listen Only Mode for Modbus communications.
The response data field returns the total quantity of messages that the slave has detected
in the communications system since its last restart, clear counters operation, or power-up.
The response data field returns the quantity of CRC errors encountered by the slave
since its last restart, clear counters operation, or power-up.
The response data field returns the quantity of Modbus exception responses returned by
the slave since its last restart, clear counters operation, or power-up.
The response data field returns the quantity of messages addressed to the slave, or
broadcast that the slave has processed since its last restart, clear counters operation, or
power-up.
The response data field returns the quantity of messages addressed to the slave for
which it sent no response (neither a normal response nor an exception response) since
its last restart, clear counters operation, or power-up.
The response data field returns the quantity of messages addressed to the slave that it
could not handle due to a character overrun condition since its last restart, clear counters
operation, or power-up
19 (Not supported)
20 (Not supported)
21 (Not supported)
Diagnostic counters
Bus Message Counter The total number of messages that the slave device
has detected in the communications system since its
last restart, clear counters operation, or power-up.
Bus Communication Error Counter The number of CRC or LRC errors encountered by
the slave device since its last restart, clear counters
operation, or power-up.
Bus Exception Error Counter The number of Modbus exception responses sent by
the slave device since its last restart, clear counters
operation, or power-up.
RVT communication through Modbus, USB or TCP/IP protocol Modbus function codes - 15
Slave Message Counter The number of messages addressed to the slave
device or broadcast that the slave device has
processed since its last restart, clear counters
operation, or power-up.
Bus Character Overrun Counter The number of messages addressed to the slave
device that it could not handle due to a character
overrun condition since its last restart, clear counters
operation, or power-up .
02 ILLEGAL DATA ADDRESS The data address or number of items received in the
query is not allowable or correct for the slave device.
The slave device will send this exception response if
an attempt to read or write part of a multiple register
database object is detected. Possible objects are
time, strings and counters
03 ILLEGAL DATA VALUE A value contained in the query data field is out of
range. The contents of the register or the status of
the coil has not changed (see paragraph 4.3).
04 SLAVE DEVICE ABORT An unrecoverable error occurred while the slave was
attempting to perform the requested action. This
may happen when the access level for changing a
parameter is not reached (see paragraph 4.2).
16 – Modbus function codes RVT communication through Modbus, USB or TCP/IP protocol
When the 16–bit CRC (two 8–bit bytes) is transmitted in the message, the low-order byte
will be transmitted first, followed by the high-order byte.
/*-----------------------------------------------------------------
FUNCTION : This routine calculates the crc high and low byte of a
message.
-----------------------------------------------------------------
INPUT PARAMETERS : buf -> Array containing message to be sent to
controller
start -> Start of loop in crc counter, usually 0.
cnt -> Amount of bytes in message being sent
to controller
-----------------------------------------------------------------
OUTPUT : temp -> Returns crc byte for message.
-----------------------------------------------------------------
*/
word crc(byte *buf,word start,word cnt)
{
word i,j;
word temp,temp2,flag;
temp=0xFFFF;
for (i=start; i<cnt; i++)
{
temp=temp ^ buf[i];
for (j=1; j<=8; j++)
{
flag=temp & 0x0001;
temp=temp >> 1;
if (flag) temp=temp ^ 0xA001;
}
}
/* Reverse byte order. */
temp2=temp >> 8;
temp=(temp << 8) | temp2;
temp &= 0xFFFF;
return(temp);
}
RVT communication through Modbus, USB or TCP/IP protocol Modbus function codes - 17
4 TCP/IP – UART protocol specification
The server will allow local and distant access to the RVT. 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.
4.2.1 TCP/IP
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.
18 – TCP/IP – UART protocol specification RVT communication through Modbus, USB or TCP/IP protocol
The RVT can be connected directly to a LAN or through Internet
4.2.2 USB
The USB interface is used to present the RVT as a serial interface on its USB port.
RVT communication through Modbus, USB or TCP/IP protocol TCP/IP – UART protocol specification - 19
4.3 Framing layer & Command layer
The data can be accessed by different means:
The server will allow local and distant access to the RVT. 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.
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.
Command &
Authentication
Layer
Framing
Layer
TCP/IP
USB
20 – TCP/IP – UART protocol specification RVT communication through Modbus, USB or TCP/IP protocol
Those two layers will use the same format regardless of the actual “transmission medium”
used.
The Windows DLL (chapter 6) incorporates all framing and command issues needed to
communicate with the RVT.
RVT communication through Modbus, USB or TCP/IP protocol TCP/IP – UART protocol specification - 21
5 Data table
5.1 Overview
There’s quite an extensive set of parameters available in the RVT.
The individual parameters have been put together in groups to ease manipulation and
transfers between the different layers of the application.
This will allow the lower layer to be quite independent from the parameters contained
within the group.
Groups that are needed by the lower layers. They will have known and fixed
group IDs in all different applications.
Groups which are specific to an application. Their IDs will be known by the
applicative layer. The lower-layers won’t know the internals of these parameter
groups.
Allowed IDs
Type Sub-type Access type
Lower Upper
Universal R/W 0x0000 0x0FF
Configuration Access protected R/W 0x0100 0x07FF
Application Specific R/W 0x0800 0x0FFF
Measurement Application Specific R 0x1000 0x1FFF
Universal R 0x2000 0x20FF
Info
Application Specific R 0x2100 0x2FFF
The access type is given from the perspective of the local or distant user interface.
The “Configuration – Access Protected” parameters can be modified by users that have
at least “Configurator” rights so that their value can be reset or modified.
The “Configuration – Application Specific” parameters can be modified by users that have
at least “Configurator” rights.
Values of single parameters within a group can be of different types. Here is a list of
these types and the associated memory usage:
Note: The RVT returns automatically to AUTO mode when the touch screen is not
pressed for more than five minutes.
5.4.1 Configuration
5.4.1.1 Universal
These are the different groups with their size, type and assigned group IDs:
5.4.1.5 Universal
These are the different groups with their size, type and assigned group IDs:
A few data specifies how and where the data is available or can be programmed.
Parameters settings values have a limited range. If a written value exceeds the minimum
and maximum allowable values, the written group of parameter will be omitted.
1/ Byte offset - Offset in bytes of the data into the Group of parameters
4/ RVT - Applicable for the RVT 6 or 12. Some data are not available
11/ Modb @ - Base Modbus address where the data is located while
The Year 0 is defined as 1900 i.e. the year 2010 will be encoded as 110.
Value Description
1 300 bauds
2 600 bauds
3 1200 bauds
4 2400 bauds
5 4800 bauds
6 9600 bauds
7 19200 bauds
8 38400 bauds
9 57600 bauds
Parity Signification
0 No parity
1 Even
2 Odd
Value Description
0 1 stop bit
1 2 stop bit
Value Description
0 DHCP disabled
1 DHCP enabled
Value Description
0 Undone
1 Done
Value Description
1 Unlocked
0 Locked
The communication from the user to the RVT is limited to the reset of data, it means that
all the Group ID is transmitted with some data set to 0 and 0:0:0:0:0:0.
The communication from the user to the RVT is limited to the reset of data, it means that
all the Group ID is transmitted with some data set to 0 and 0:0:0:0:0:0.
The communication from the user to the RVT is limited to the reset of data, it means that
all the Group ID is transmitted with some data set to 0 and 0:0:0:0:0:0.
The communication from the user to the RVT is limited to the reset of data, it means that
all the Group ID is transmitted with some data set to 0 and 0:0:0:0:0:0.
100 peak Temperature max T6 °C/°F * * Float 4 -40 -40 150 30451
120 peak Temperature max T7 °C/°F * * Float 4 -40 -40 150 30461
130 peak Temperature min T7 °C/°F * * Float 4 150 -40 150 30466
140 peak Temperature max T8 °C/°F * * Float 4 -40 -40 150 30471
150 peak Temperature min T8 °C/°F * * Float 4 150 -40 150 30476
The communication from the user to the RVT is limited to the reset of data, it means that
all the Group ID is transmitted with some data set to 0 and 0:0:0:0:0:0.
The communication from the user to the RVT is limited to the reset of data, it means that
all the Group ID is transmitted with some data set to 0 and 0:0:0:0:0:0.
Bidirectional update is necessary to let the user set the data in manual mode and retrieve
calculated value after auto commissioning.
Value Description
0 Fixed OFF
1 1Ph L1
2 1Ph L2
3 1Ph L3
4 3Ph
5 Fixed ON
Value Description
0 No change
1 Ask for at least 1 more step
Value Description
0 No change
1 Ask for at least 1 more step
These step statuses are updated according to the Auto mode or Manual mode.
Value Description
0 Relay to open
1 Relay to close
This table contains the alarm messages and the time stamp of their occurrences.
Time stamp.
When the buffer is full, the eldest alarm in the buffer is overwritten with the new one and
the index is incremented.
Value Description
0 1Ph-1LL1
1 3Ph-1LL1
2 3Ph-1LN1
3 3Ph-3LL3
4 3Ph-3LL2
5 3Ph-3LN3
6 3Ph-1LL3
7 3Ph-1LN3
Value Description
0 Linear
1 Circular
Value Description
0 Progressive
1 Direct
Value Description
0 Normal
1 Integral
Value Description
0 English
1 French
2 Deutsch
3 Spanish
4 Chinese
Value Description
0 °C
1 °F
Value Description
0 Auto
1 Manual
2 Set
Value Description
0 Unlocked
1 Locked
Value Description
0 Disabled
1 Enabled
Value Description
0 Disconnection & alarm
1 Disconnection only
Positive values are for passive loads. Negative values represent regenerative mode.
Value Description
0 RVT version
1 RVT 3-phase version
Value Description
0 Unlocked
1 Locked
5.5.4 Measurement
Value Description
0 Relay open
1 Relay closed
Value Description
0 External input reset
1 External input set
Value Description
0 Reset
1 Set
Value Description
0 Reset
1 Set
These variables are providing information about the current network configuration.
When DHCP is disabled, those values will be the same as the one from the Ethernet
Data parameter.
When DHCP is enabled, those values will be different than the static ones provided in the
Ethernet Data parameter.
Byte Size in
Description Units RVT RVT3P Data type # elts Min value Max value
Offset bytes
0 Voltage Spectrum L1-L2 V * Float 4 49 -9e6 9e6
These IDs will have to be used in the TCP/IP server/client command requesting to gather
some curve information.
6.1 Introduction
This document describes the interface of the Windows Communication DLL.
The interface is heavily based on the protocol described Chapter 4 of this document.
This document will focus on the differences with the protocol. Indeed, to ease the life of
DLL user, some code has been added to handle annoying parts of the protocol.
Moreover, to be compatible with Visual Basic 6.0, some types have had to be modified as
VB does not support certain types (unsigned 16-bits integer for example).
6.2 Interface
6.2.1 Introduction
All exported library functions follow some similar syntax:
COMMANDCLIENTDLL_API int __stdcall CommandClient_Fct(…);
All functions return an integer providing an error code to the calling layer.
The “__stdcall” specifier is used to indicate that the calling convention to be used is the
standard one.
Special care has been taken so that the function names exported by the DLL are the
same as the ones defined above.
6.2.2.1 CommandClient_Init
This function opens the connection to the RVT.
RVT communication through Modbus, USB or TCP/IP protocol Windows Communication DLL / Interface Specification - 51
The ConnectionType can take two values:
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 RVT again.
6.2.2.2 CommandClient_Clean
This function closes the connection to the RVT.
The closing allows to free resources allocated both on the PC side and on the RVT side.
6.2.3 Authentication
Please note that the user account covered here are applicative user account handled by
the RVT.
Once the TCP/IP, USB or Modbus connection has been established to the server, the
client must authenticate itself.
As the system can be accessed remotely, some basic authentication is put in place. This
allows distinguishing users and granting them certain rights to do things.
This authentication is mentioned as the first point of the command layer for the very
important reason that no command will be accepted before an authentication is
performed. The only exception is for the local administrator user that is automatically
detected based on its local connection to the server.
6.2.3.1 CommandClient_Authenticate
This function allows authenticating as a given user on the RVT.
The password is here given as a string and transformed by the DLL to be used in the
protocol.
The Login and Password parameters are used to authenticate oneself and the
AccessLevel is returned to indicate the associated access level.
52 – Windows Communication DLL / Interface Specification RVT communication through Modbus, USB or TCP/IP protocol
Access levels
6.2.3.2 CommandClient_CreateUser
This function allows creating a new user account on the RVT.
The password is here given as a string and transformed by the DLL to be used in the
protocol.
The AccessLevel parameter specifies what access level to associate with the new user
account.
6.2.3.3 CommandClient_DeleteUser
This function allows deleting a user account on the RVT.
6.2.4.1 CommandClient_GetParameter
This function allows getting a parameter group from the RVT.
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.
RVT communication through Modbus, USB or TCP/IP protocol Windows Communication DLL / Interface Specification - 53
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.
6.2.4.2 CommandClient_SetParameter
This function allows setting a parameter group in the RVT.
One must have at least Configurator rights to set application specific parameters and at
least administrator rights to set universal parameters.
6.2.4.3 CommandClient_ApplyParameterChanges
This function applies the shadowed parameter changes in the parameter memory of the
RVT.
6.2.4.4 CommandClient_ConvertRVTtoVB
This helper function allows retrieving a single parameter value from a parameter group.
The Offset and ValueType are specifying where to find the wanted data and what is the
type of the wanted value.
The OutputString and OutputStringSize are specifying where the string should be placed
and what its size is.
One should make sure that there’s enough space in the output buffer for the string.
Currently, the biggest parameters defined for the RVT are 180 bytes big and are of the
string type. Numbers are converted to much smaller strings.
54 – Windows Communication DLL / Interface Specification RVT communication through Modbus, USB or TCP/IP protocol
6.2.4.5 CommandClient_ConvertVBtoRVT
This helper function allows setting a single parameter value into a parameter group.
The InputString is the value to be converted and stored in the parameter group.
The Offset is specifying where to store the converted data and the ValueType is
specifying what type of data should be written to the parameter group.
One should make sure that the Offset and ValueType will not cause writing out of the
ParamGroupValue buffer.
The curves will be too big to be retrieved with a single command. As a consequence, the
data will be split in chunk. The server is specifying the size of those chunks and is
warning the client of how many of those chunks will need to be transferred to get the
complete curve.
The Trigger Value to be used is here provided as a string and is converted by the DLL to
the type specified by TriggerValue_Type.
It can take some time between the moment of the request and the time where the first
data gets available.
IMPORTANT NOTE:
6.2.5.2 CommandClient_RequestCurve
This is a simplified version of the CommandClient_RequestCurveEx command where
triggering is disabled.
6.2.5.3 CommandClient_ReleaseCurve
This function is telling the RVT 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.
6.2.5.4 CommandClient_GetCurve
This function is getting curve data from the RVT.
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.
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.
6.2.5.5 CommandClient_GetCurveIDs
This function is getting all the SourceIDs currently in use by the DLL.
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.
56 – Windows Communication DLL / Interface Specification RVT communication through Modbus, USB or TCP/IP protocol
6.2.5.6 CommandClient_GetCurveCharacteristics
This function is getting the characteristics of a given curve.
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 RVT.
6.2.6 Miscellaneous
Reset
After calling this command, the connection should be closed using the
CommandClient_Clean function and should be re-established again.
6.3.2 Multi-threading
The DLL is not coded for multi-threaded application.
The first consequence is that all calls to the DLL should be called from a single thread.
Calling from different thread could be possible but protection should then be implemented
outside of the DLL.
The second consequence is that all calls to the DLL are blocking. In usual cases it is not
a problem but when the connection gets lost for example, it could take a short amount of
time to return from a called function.
The only alternative is to go for non-blocking behaviour but then the programming of the
application will become more complex as a request issued would not have a direct
answer with data to process but the answer would come at a later asynchronous stage.
RVT communication through Modbus, USB or TCP/IP protocol Windows Communication DLL / Interface Specification - 57
6.3.3 Sequence of actions
The following sequence of action should be followed when using this DLL to
communicate with a RVT:
One should not forget the authentication phase otherwise no subsequent action will be
possible and the connection will be closed by the RVT. Moreover, the authentified user’s
access level will make it possible to perform certain actions or not.
Unwanted TCP/IP or serial disconnections with the RVT can be monitored through the
callback provided at initialization time or through the returning o of the
“RVT_SYS_SOCKET_DISCONNECTED” code. When that is happening, it is necessary
to call the clean function and try to connect to the RVT again.
58 – Windows Communication DLL / Interface Specification RVT communication through Modbus, USB or TCP/IP protocol
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
The form code contains necessary initialization steps to make the DLL available from
another directory. It obviously also contain the code for the user interface and associated
calls to the DLL functions.
The module contains the necessary constant and function declarations. It also contains
some helper functions to be used when using helper functions to convert parameter;
these functions take care of memory allocation for the returned strings.
RVT communication through Modbus, USB or TCP/IP protocol Windows Communication DLL / Interface Specification - 59
7 Network / Internet connection principles
7.1 Introduction
This document gives some principles on how the RVT Touchscreen can be accessed on
a local network from the Internet.
The principles are put in practice using a given single hardware namely a Thomson
Speedtouch ADSL modem/router followed by a non-managed switch.
Even though certain terms will differ from one piece of hardware to another or certain
functions will be accessible in a different manner, all in all the principles will remain the
same.
3. There could possibly be a switch or other routers between the RVT Touchscreen
and the modem.
4. A workstation also connected to the Internet would want to access the RVT
Touchscreen to get information.
In this topology, all the machines behind the modem belong to a private network.
They can access the Internet because the modem will remember who tried to access
what and send the response from the Internet to the correct device.
60 – Network / Internet connection principles RVT communication through Modbus, USB or TCP/IP protocol
At the same time, the devices cannot be accessed from the Internet because their IP
address is purely private; they do not have a public address and cannot be accessed
directly as a consequence.
This is the base of the “problem” (might be the required behavior, for security reasons).
The RVT Touchscreen cannot be accessed from the outside world because it has a
private address.
7.3.1 Principle
To communicate with a RVT Touchscreen, one must open a connection to the RVT on
the TCP port 4250.
Port forwarding allows redirecting requests aimed at an inbound public port to a device on
the local LAN network.
The forwarding mechanism should allow redirecting the requests to a port of the local
device that is different from the inbound public port.
In the example shown above, the router should be configured so that accesses on its
public address on the TCP port 4250 gets forwarded to the 192.168.2.40 device on the
same port.
RVT communication through Modbus, USB or TCP/IP protocol Network / Internet connection principles - 61
7.3.2 Speedtouch router example
Note: the configuration will be different for another router.
The first consist in creating a “Game or application” rule that specifies the port to be
forwarded:
62 – Network / Internet connection principles RVT communication through Modbus, USB or TCP/IP protocol
The second phase consists in applying the freshly created rule to a given network
address:
When those two phases are done, the requests coming on the 4250 port on the modem’s
public address will get forwarded to the device having the 192.168.2.40 address i.e. the
RVT Touchscreen.
7.4.1 Principle
The RVT Touchscreen is now accessible from the outside world.
The public IP address of the modem is to be used when trying to connect to the RVT
Touchscreen.
If the address is assigned dynamically by the Internet Service Provider, some extra
configuration work is required.
RVT communication through Modbus, USB or TCP/IP protocol Network / Internet connection principles - 63
7.4.2 Example when using static public IP address
The IP address can be found from the modem interface:
The address can be used to access the RVT Touchscreen from the outside world.
Note that even when the ISP dynamically updates the address, the address can be used
to access the RVT Touchscreen.
The constraint in that case is that checking this page needs to be done for every refresh
of the address by the ISP.
This allows the public IP address to be linked to a DNS name (like google.com) which
can be used in place of the IP address.
7.5.1 Principle
An account is created on a dynamic DNS service provider.
This links a DNS human internet name to a given user & host (our modem in this case).
A client must run on the local network to update the DNS information when the IP
address changes. This is sometimes embedded within the modem/router services or it
can be present in Network Access Storage devices services. It can be found as
applications running on servers & PCs of course.
There are several providers of such services, some of them are free.
64 – Network / Internet connection principles RVT communication through Modbus, USB or TCP/IP protocol
7.5.2 Creating a no-ip account
One must go to http://www.no-ip.com and register for an account:
RVT communication through Modbus, USB or TCP/IP protocol Network / Internet connection principles - 65
7.5.3 Adding a host
Once the account is created, the RVT Touchscreen should be added as a host so that
no-ip knows its human name:
The RVT Touchscreen can now be accessed through the rvt2.no-ip.org name.
This is however only valid until the next change of public IP address. That is why the
modem/router should now be configured to update automatically the new IP address to
no-ip.
66 – Network / Internet connection principles RVT communication through Modbus, USB or TCP/IP protocol
The RVT Touchscreen can now be accessed through the testrvt2.no-ip.org name
regardless of the changes in the actual public IP address:
7.6 Notes
This is due to some routers that do not allow such a routing (trying to connect to the
public address of the RVT Touchscreen from the same local LAN network than the RVT).
• Port forwarding
• Game & Application sharing as in the Speedtouch used for the example
• …
• …
RVT communication through Modbus, USB or TCP/IP protocol Network / Internet connection principles - 67
Indeed, certain routers are capable of forwarding traffic to a device with a known MAC
address. In that case, the actual IP address of the device is of no interest and therefore
DHCP could be used.
If the router is only capable of forwarding to a given IP address then using a static
address on the RVT Touchscreen is mandatory. When doing so, one has to ensure that
the default gateway address is configured to match the one of the router so that the
outgoing traffic will be going to the right destination.
68 – Network / Internet connection principles RVT communication through Modbus, USB or TCP/IP protocol
8 Appendices
A1 List of abbreviations
Common The voltage reference point of a circuit. It may or may not be connected to
earth ground, though it is generally assumed to be at zero volts, unless
otherwise indicated. In floating circuits, the common is sometimes at a
relatively high potential. This term is sometimes used interchangeably with
the term “Ground” or GND
Hexadecimal or HEX A number system using a decimal 16 as its base. A single digit number in
HEX ranges from 0 to 15, represented by 0 to 9 and A to F.
The architecture of the Industrial IT system. The architecture defines how the
system is built, in terms of basic concepts, underlying technologies, system
topology, modularity, and mechanisms for interaction between different parts
of the system. It also defines concepts, rules, and guidelines that a
component must comply with in order to fit in the Industrial IT system. A
central feature of the IIT architecture is that information and functions are
centred on Aspect Objects.
IT
Industrial Enabled A product that is Industrial IT enabled has been verified according to the
process of Industrial IT certification. It has the right to use the “Industrial IT
enabled” symbol.
Loopback A test used for checking functionality of a serial port, utilizing a test plug that
connects send, receive and handshaking signals
MAC address In computer networking, a Media Access Control address (MAC address) is
a unique identifier assigned to most network adapters or network interface
cards (NICs) by the manufacturer for identification, and used in the Media
Access Control protocol sub-layer. If assigned by the manufacturer, a MAC
address usually encodes the manufacturer’s registered identification
number.
Measurement A measurement is a value computed by the controller through its analog and
digital inputs. Measurements can be read from the RVT front plate, or
through the Modbus protocol.
Modbus adapter It is an optional small interface module through which the RVT is connected
to an external Modbus serial communication bus. It performs an optical to
RS485 conversion. The communication with the Modbus adapter is activated
with an RVT parameter.
OPC OLE™ for Process Control. OPC is Plug-n-Play in the field of Automation
and HMI. OLE™ for Process Control (OPC™) is the most standard way for
connecting hardware and data devices with HMI client applications.
OPC Servers OPC Server applications are used to collect data from the data sources like
hardware devices. At the bottom level, the servers are mainly for reading
inputs and writing outputs of the data sources. At the upper level, the servers
make the data available in a standard way to the OPC client applications.
OPC Clients The OPC Client applications can communicate directly with the OPC servers
and get the data. This way OPC enhances the interface between client and
server applications by providing a standard mechanism to communicate data
from a data source to any client application.
Parameter A parameter is an operating data for the controller. Parameters can be read
and programmed with the RVT front plate, or through the Modbus protocol.
Parity Simple method of data error checking performed at the byte level. May be
user-specified as Odd, Even or None with most equipment and software.
PC Personal Computer
IT
Power Power Factor Controller
Rx See Receive
Time-out Parameter specifying the max. wait time in ms. Waiting for a response in the
range 0..10000 ms.
SMTP Simple Mail Transfer Protocol (SMTP) is an Internet standard for electronic
mail (e-mail) transmission across Internet Protocol (IP) networks. SMTP is
specified for outgoing mail transport.
While electronic mail servers and other mail transfer agents use SMTP to
send and receive mail messages, user-level client mail applications typically
use only SMTP for sending messages to a mail server for relaying. For
receiving messages, client applications usually use either the Post Office
Protocol (POP) or the Internet Message Access Protocol (IMAP) or a
proprietary system (such as Microsoft Exchange or Lotus Notes/Domino) to
access their mail box accounts on a mail server.
Tri-State The ability of a communications transmitter to turn its circuitry off, reducing
the load on the network
Tx see Transmit
A2 References
RS485 Modbus adapter operating manual
www.abb.com/lowvoltage