Help Topics

Help Topics for MBProbe

Starting MBProbe
Start Parameters
Accessing the User Interface
Setting Communications Parameters
Reading Data
Writing Data
Errors

MBProbe

About:

MBProbe is an interactive user tool for reading and writing to Modbus/TCP field devices. It can be used for testing, troubleshooting, and commissioning of field devices such as valves, sensors, PLCs and other equipment.

MBProbe is server based and is accessed via a web browser. The server and the web browser do not have to be on the same computer.

Starting MBProbe:

The MBProbe program can be started as follows:

For Linux:


	./mbprobe.py

For MS Windows:


	c:\python25\python mbprobe.py

For MS Windows, the first part of the path ("c:\python25\python") will depend on where you installed Python, and what version you have installed. If you have installed it in a non-standard location you will need to specify the path to where you have actually installed it. If you have installed a version other than 2.5, you will need to change the "python25" to match the appropriate version (e.g. for version 2.6, use "python26").

Start Parameters:

When starting the system as shown above, the defaults will be used as the initial parameters, and any others must be changed manually. It is possible to specify certain parameters on the command line in order to have the system automatically use those parameters on start up. The start parameters are defined as follows:

p = The port for the web server used by the user interface. The default is 8680.
h = The host name (address) of the remote field device you wish to connect to. The default is 'localhost'.
r = The port number for the remote field device. The default is 502.
u = The Modbus unit ID for the remote field device. The default is 1.
t = The time-out (in seconds) to use for communications with the remote field device. The default is 5.0
c = Connect on start-up. If "-c y", the system will automatically connect to the field device on start up. For any other value, the connect must be made manually. The default is to connect manually.
a = Auto reconnect on disconnect error. If "-a y", the system will automatically re-connect to the field device if there was a connection error (e.g. the connection was closed from either end). The default is to automatically re-connect. If auto-connect was selected and connect on start up was not selected, the connection will automatically be made using the current parameters when a read or write request is made.

Example for Linux:


	./mbprobe.py -p 8680 -h localhost -r 502 -u 1 -t 30.0 -c y -a y

Example for MS Windows:


	c:\python25\python mbprobe.py -p 8680 -h localhost -r 502 -u 1 -t 30.0 -c y -a y

Accessing the User Interface:

The user interface is accessed via a web browser. The user interface consists of four web pages:

Help (help.html) - The on-line help system.
Set Parameters (setparams.html) - Set or change the parameters for communicating with the field device.
Read Data (readdata.html) - Read data from the field device.
Write Data (writedata.html) - Write data to the field device.

To access any of the web pages, enter the URL of the web page into your web browser, including the page name, the host for the web server (not the one for the field device), and the port number for the web server (not the one for the field device). For example:


	http://localhost:8680/help.html

The host name ("localhost" in this example) and the port number ("8680" in this example) may be different depending upon how and where you have installed the system. The example shown above will access the help web page.

Once you have accessed on web page, the others are accessible via a menu located near the top of each page. It may be a good idea to bookmark the web page to make it easier to access next time.

Setting Communications Parameters:

The web page for "Set Communications Parameters" can be used to set or change the parameters for communicating with the field device.

On the left side of the page are a series of input boxes which allow you to specify the following information.

Host - The host name or IP address for the field device. E.g. 'localhost', '127.0.0.1', etc.
Port - The port number for the field device. For most Modbus/TCP devices this would be 502. However, an alternate port may also be specified if necessary.
Time out - This is the time-out (in seconds) for communicating with the field device.
Unit ID - The Modbus unit ID for the field device. For many devices the unit ID does not matter. For those for which it does matter, the correct value may be specified here.
Connect/Disconnect - This is a pair of "radio buttons" which allow you to disconnect from or reconnect to the field device.
Auto-Connect - This is a check box which allows you to set whether the system will automatically connect if a connection error occurs. When the check box is ticked, auto reconnect is selected.

Below the input boxes will be a large push button labelled "Apply". When this button is pressed, the parameters specified above will be applied.

To the right of input area is a column showing the current parameters. These may differ from the parameters in the input area if the values were edited but not applied. In addition, there will be a message in large text indicating whether the system is currently connected or not.

The following error message may be displayed: "Error - Could not establish contact with remote host." This indicates that the system attempted to connect with the field device, but either the field device could not be contacted, or else it refused the connection.

This page does not allow you to change the port number used by the web server. That must be set as a command line parameter (see above).

Reading Data:

Data may be read from the field device by using the "Read Modbus Data" web page. This page has 20 sets of inputs allowing you to read up to 20 different addresses at the same time. Each input area specifies a single data table value.

Specifying Parameters:

Each input area provides a drop down list allowing you to specify coil, discrete input, holding register, input register, or none. If you select "none" that input area will be disabled. In addition, you can enter the Modbus data table address.

When you have specified the desired address type and address, click on the large "Read Data" button located at the bottom of the screen. The system will then send a series of Modbus/TCP requests to the field device. When the field device has responded to the queries, the web page will be refreshed to show the data which was read beside each of the input areas (or blank if that input area was unused). If there were any errors, an error message will be displayed in place of the data.

Clearing (Resetting) the Page:

Beside the "Read Data" button is a pair of "radio buttons" allowing you to select either "Read Data" or "Clear Page". Selecting "Read Data" allows for normal operation. Selecting "Clear Page" causes the input areas to be reset to their default values when the "Read Data" button is pressed. When clearing (resetting) the page, no messages are sent to the field device and no data is read.

Modbus Functions Used:

The system will send an individual Modbus/TCP request for each address specified. The following Modbus functions are used:

Coils - Function 1.
Discrete inputs - Function 2.
Holding registers - Function 3.
Input registers - Function 4.

Each function is used with a quantity of 1.

Writing Data:

Data may be written to the field device by using the "Write Modbus Data" web page. This page has 20 sets of inputs allowing you to write up to 20 different addresses at the same time. Each input area specifies a single data table value.

Specifying Parameters:

Each input area provides a drop down list allowing you to specify coil, holding register, or none. If you select "none" that input area will be disabled. In addition, you can enter the Modbus data table address and the data to be written.

When you have specified the desired address type, address, and data, click on the large "Write Data" button located at the bottom of the screen. The system will then send a series of Modbus/TCP requests to the field device. When the field device has responded to the queries, the web page will be refreshed. If there were any errors, an error message will be displayed to the right of each input area.

Clearing (Resetting) the Page:

Beside the "Write Data" button is a pair of "radio buttons" allowing you to select either "Write Data" or "Clear Page". Selecting "Write Data" allows for normal operation. Selecting "Clear Page" causes the input areas to be reset to their default values when the "Write Data" button is pressed. When clearing (resetting) the page, no messages are sent to the field device and no data is written.

Modbus Functions Used:

The system will send an individual Modbus/TCP request for each address specified. The following Modbus functions are used:

Coils - Function 5.
Holding registers - Function 6.

Errors:

Internal Errors:

The following error messages are generated internally in the system.

Connection error - The system could not communicate with the field device. Either the connection was not made, or the field device has disconnected.
Invalid address - The address is in an invalid format.
Invalid data format - The data is in an invalid format.

Auto Reconnect:

If auto reconnect is selected and a connection error occurs while attempting to read or write data, the system will attempt to reconnect once for each data item until either a successful connection is made or until attempts (and failures) for all the data items have been made.

Modbus Exceptions:

The following messages represent Modbus exceptions which were returned by the field device.

Unsupported function - The field device has responded with Modbus exception code 1. The function code (address type) used is not supported.
Invalid address - The field device has responded with Modbus exception code 2. The address requested does not exist in the field device.
Too many data values - The field device has responded with Modbus exception code 3. This would normally mean the system has requested too may data table addresses at one time. However, the system only requests one data table address at a time, so this message should not appear unless the field device is returning incorrect exception codes.
Undefined error- The field device has responded with Modbus exception code 4. The meaning of this will depend on the field device (this is device specific).