HMI Modbus

User manual v1.18

Developed by Sagram.net

Contact: [email protected]
 Contents

1. The program objectives

2. Description of the features of the program
3. User interface description
3.1. Start screen
3.2. Main screen, element creating and editing
3.3. Main menu
3.4. Multiple working screens
3.5. Elements group operations
3.6. Scaling elements
4. Communication settings
4.1. Server list
4.2. Setting element communication parameter
5. Element description
5.1. Bit lamp indicator, bit switch (bit button)
5.2. Text, numeric input
5.3. Progress bar, seekbar
5.4. Chart
5.5. Image
5.6. IP camera
6. Start / stop communication project
7. Log communication, error analysis
8. Exit the program
9. Project Viewer (runtime)
1. The program objectives

HMI Modbus is designed for communication between Android-based devices

with any device that supports Modbus communication protocol. HMI_Modbus may be
used instead of a simple operator panel for reading and writing the bit and byte values.

Other possible example of using this software – «Smart house» for monitoring and
setting parameters of the equipment.

HMI Modbus application located on Google Play:

https://play.google.com/store/apps/details?id=net.sagram.hmi_modbus

2. Description of the features of the program

Software is capable to use one of communication protocols:

1. Modbus TCP/IP via Wi-Fi, or mobile connection

2. Modbus RTU via Bluetooth connection

Supported protocol commands:

1. 0x01 – Read Coil Status.

2. 0x02 – Read Discrete Inputs.
3. 0x03 – Read Holding Registers.
4. 0x04 – Read Input Registers.

Supported data types:

1. Int 16 – integer, 2 bytes.

2. Int 16 unsigned – unsigned integer, 2 bytes.
3. Int 32 – signed integer, 4 bytes.
4. Float – floating point value, 4 bytes.
5. Float swapped – swapped float, LOW word ad HIGH word are swapped, 4
bytes.
3. User interface description

3.1 Start screen

At program start, user will see starting screen shown on fig.1:

6
Fig 1. Start screen.

Following operations can be executed on this screen:

1. Create new project: creates new project with a new project name. If project
name already exists, no project will be created. Project name can consist latin
letters, numbers, “-“ and “_” symbols. Using any other symbol can lead to
project compatibility lost. By default, project with “default” name will be
created.
2. Load last project: loads most recent project, that was edited and saved by user.
3. Load project: loads project from a project list.
4. Delete project: delete project from a project list and on device.
5. Exit: Quits program.
6. “Load from” Switch: switches load path –
/data/data/net.sagram.hmi_modbus/databases or external path.
3.2 Main screen, element creating and editing

Touch “+” button placed on bottom right on main screen to add new element. In
order to change element collection, you need to swipe left or right on add element panel.
Main screen appearance with add element panel shown on fig 2.

Show navigation Communication Cancel

panel start

Main menu

Ancillary panel
Switch
collection groups

Project Elements (can be

elements added in your project)

Fig 2. Main editing screen appearance

Long tap on element on add element panel will add this element on editing screen.
Long tap on element, already placed on editing screen, allow to move this element.

In order to remove element from the screen, you need to move this element out of
screen borders.

Short tap on element will show floating menu, from where further element
settings can be made.
 Floating menu consists of:

1. Element settings – sets following parameters of element interface:

a. Text settings – user sets element text here, in case that elements has
several states (button for emample) you can set different output text for
each state. Font size and text alignment also sets here.
b. Drawing color – for text elements sets text color, for chart sets series
trend color.
c. Background color – set element background color. If element backroad is
bitmap image, this setting will take no effect.
d. Width – element width.
e. Height – element height.
f. Left offset – sets element offset from left side of screen (x – horizontal
offset)
g. Top offset – sets element offset from top of the screen (y – vertical
offset).
2. Change size – changes element size (shows adjusting dot on element borders).
3. Copy element – create element`s copy on main editing screen.
4. Delete – deletes element.
5. Choose server – shows server list screen. Described in chapter “Server list”
6. Communication – only active is server for this element is already set. On
press, will show communication settings screen. Described in detail in
"Communication settings chapter".
7. Address – communication address sets here. This parameter can also be set on
communication setting screen.
After element move, delete , create, or any other operation you can undo last
action by pressing " Cancel" on application top panel.

An attempt to establish connection will be made on “Start” button on the top of the
screen. In case of success, communication will start. To stop communication, press
“Stop” button. On communication start project will be saved with “auto_save” project
name. To restore damaged project from this save point, you need to get to the main
menu, load project named “auto_save” and save it with a new project name.
3.3 Main menu

After project creating or loading user gets to a main working screen. Pressing
“settings” button shows main menu, from where user can adjust following:

1. Common settings are used to adjust project most important parameters.

It includes:
a. Screen orientation – portrait or landscape. Sets screen mode and elemets
placement.
b. Grid settings – sets grid visibility.
c. Bound to grid – if this set to true, element placement will be fixed on grid
nodes.
d. Grid size – sets distance between grid nodes.
e. Request timing – sets time between communication request: in case of
large amount of request it is necessary to set this value 0.
f. Communication timeout – response awaiting time, on expire,
communication error event will be triggered.
g. Scale coefficient – allows to increase (decrease) all elements on screen.
Used on transferring projects between devices with different screen
resolutions.
2. Save – saves project with its existing name.
3. Save as – saves a project with a new name.
4. Edit server list – shows server list edit screen. Described in chapter 3.3.
5. Show log – shows requests and responses communication log in hex. Used for
project diagnosis an dubugging.
6. Export project – export project to a user defined path (by default projects are
stored in program folder: /data/data/net.sagram.hmi_modbus/databases).
7. About – shows a brief information about program, developer contacts. This
program is still in developing stage, so feel free to send your suggestions and
remarks. Email: [email protected]
3.4 Multiple working screens

Navigation panel for managing working screens can be called by left-to-right slide
on left screen side or by pressing "≡" on upper-left corner of the screen.

By default, project have only one screen called “Screen#1”. In order to add screen
to project press “Add new screen” button – new screen dialog will be shown. To create
screen, press “+” button on upper right, and set a name for this screen. Screen editor is
shown on fig 3.

Add screen

Screen button
Change screen
order

Screen menu

Fig 3. Screen editor

On screen button press floating screen menu will appear:

1. Set background image – allows user to set a bitmap image as background.

Image will be resized to fit in screen size. This function is used for customize
user project and adding more sophisticated graphics.
2. Rename – sets a new name for existing screen
3. Remove – deletes screen. If screen was deleted mistakenly, go to editor screen
and press “undo” button.
To change screen switching order press up-down keys on he right side of screen
buttons.

To switch between screens press screen button in navigation panel

3.5 Elements group operations

To start group work with elements user should select required elements. To do this,
touch free area on editor screen, and, without press release, select elements you want to
work with. After selecting group of elements you can add (remove) element to selection
by short-tap on it. User can move selected element group by long-tap (if selected group
moves out screen border it will be deleted)

While group selection is idle, group operation panel is shown on top of the screen.
This panel allow user to perform following actions:

1. Cut – copies elements to clipboard and deletes it from workspace.

2. Copy – copies elements to the clipboard. Elements on workspace lefts intact.
3. Paste – put elements from clipboard to workspace.
4. Align– aligns elements:
a. On left edge.
b. On vertical center.
c. On right edge.
d. On upper edge.
e. On horizontal center.
f. On lower edge.
5. Choose server – sets communication server for selected group of elements.

Group operations panel is shown on fig 4. This panel can be shown on screen by
pressing "˅" button. To hide this panel press "˄" button.

Copy Paste
Cut

Fig 4. Group operation panel

3.6 Scaling elements

When you move projects between devices with different screen resolutions may be
necessary to change the size of all the elements. For this purpose, the program includes a
scaling factor. By default, it is equal to 1. If the ratio is less than 1, all of the elements
will be proportionally reduced if the opposite - increased proportionally.

Scaling is not performed automatically when you transfer the project to a new
device.

4. Communication settings

4.1 Server list

Server list screen can be called from main menu or from floating element menu.

Two types of servers are supported on this moment: TCP/IP and Bluetooth. In
order to add a new server, press corresponding button on the screen. When adding TCP
server user must set following parameters: server name (optional), IP address
XXX.XXX.XXX.XXX format and communication port (usually 502 or 8000 in most
Modbus-TCP devices).

On adding Bluetooth devices user must choose device from the list of Bluetooth-
connected devices. In case on any problems on establishing Bluetooth-connection, try
connect through default Android Bluetooth interface. To refresh connected device list use
“Device scan” button.

Long tap on server name will show floating menu:

1. Edit server parameters – sets server parameters.

2. Remove – deletes server from list.

If server list screen was called from floating element menu, then chosen server will
be applied to this element and user will be returned to main workspace.

4.2 Setting element communication parameter

After element server is set, element communication settings on element floating

menu become active.

Communication settings menu description:

1. Communication address – connected device memory register address. Refer

to device user manual for detailed description.
 2. PLC address – connected device address. Usually "0" in case of Ethernet
connection. In case of Bluetooth or Modbus Serial (by using Ethernet-Modbus
Serial converter) this address is defined on device itself, usually “1” by default.
3. Write allowed – allows connected device memory register value alteration.
Active only in communication mode. Device data will be changed according
user performed actions.
4. Notifications – engages element notifications. On notification plays standard
Android notification sound (can be changed on Android device settings) also
notification sign will show in element corner.
5. Request type – sets element request type, detailed description in element
information chapter.
6. Function code – sets element MODBUS function code , detailed description in
element information chapter.
If you need create several elements with similar communication request, you
can create one element, make required number of its copies, and then change it
communication address on element floating menu.

5. Element description

5.1 Bit lamp indicator, bit switch (bit button)

The buttons and indicators are designed to input-output the bits data. It is also
possible to record in the register Int16 values.

Any indicator can be switched to the button setting the resolution: " Allow write
request" in the communication settings.

The buttons and indicators allow you to change the image of their states. To do
this, click on the "Set drawable ..." from the popup list. You can select images from the
preset program or load an image from disk (the image must be loaded for the "OFF" and
"ON", respectively).

The buttons have notifications:

1. None – no notification.
2. Off – notification will be show during "Off" state.
3. On – notification will be show during "On" state.

It supports such requests:

1. None – disable request.

2. Read bit state (Switch) – toggles to the opposite state.
3. Set bit On – set bit "On" state.
4. Set bit Off – set bit "Off" state.
 5. Write constant Int16 – when you click records the predetermined value to the
address.

Implemented in the application these types of functions modbas:

1. Read Coil Status 0x01 – it refers to the storage registers, are available writing
and reading.
2. Read Discrete Inputs 0x02 – It refers to the storage registers, are available
only reading.

5.2 Text, numeric input

This element is used to add text on the screen, display the numerical values of the
registers and change their values. If the item only as a text, then it does not specify the
server, and the item will not be participate in communication.

The element supports the following settings: size, color, text alignment, and
background color selection.

If an element is specified server (you can choose from the popup menu), it is
possible to set the parameters for communication.

Setting up in communications settings "Number of decimal places" - specifies

how many decimal places will be displayed. This works for the following types: WORD,
DOUBLE WORD (Int16, Int32). For example, if the register contains the value 200, the
result will be displayed 2.00 (number of decimal places equal 2).

Implemented the requests that specify the data format:

1. Int 16 –16 bits value (-32767 : 32767).

2. Int 16 unsigned – unsigned 16 bits value (0 : 65535).
3. Int 32 – 32 bits value (-2147483647 : 2147483647).
4. Float – 32 bits float value (-3.402823466e+38 : 3.402823466e+38).
5. Float swapped – 32 bits float value (start and end words swapped)

Supports notification occurs with a specified comparison value:

1. None – disable notification.

2. = – equal to a specified value.
3. <> – not equal to a specified value.
4. < – less than a specified value.
5. > – larger than a specified value.
6. <= – less or equal than a specified value.
 7. >= – larger or equal than a specified value.

Value for the notification is entered in the next menu item, are supported as the
whole and the real numbers.

5.3 Progress bar, seekbar

To display the relative value is a "Progress bar", to enter the relative value of the
element, you can use a "Seekbar". These elements have the ability to set the vertical or
horizontal position, the choice of position is produced from the popup menu element.

Request type, function code and the notification similar to the element "numeric
input". Additionally, the communication settings set to the maximum value of the
progress display. The value is scaled from "0" to the specified value.

5.4 Chart
To display the value changes in real time provides an element "Chart".

In the setting of the chart: the text color matches the color graphics, text
background corresponds to the background graphics.

In addition to the standard communication settings similar item settings "numeric

input" you can enter the polling interval values. When filling out the chart axis "X" will
be performed automatically offset to the current time.

5.5 Image
To download your images on the screen you can use the element "Image". Loading
image is from the directory: Pictures / HMI_Modbus. The use of this element is not
recommended, instead of it is better to load the background of the screen image.

5.6 IP camera

The program provides the ability to view the IP camera picture. Currently
implemented only camera operation in "default" mode, camera mode support "native" is
not added. At the same time is only one element the "Camera" on the same screen. This
element in this version is under construction.
 In the camera settings, you must specify the IP address and port of the server to
connect to the camera. You also need to specify the source video to determine the name
of the video source, you can use the method: https://github.com/niqdev/ipcam-view/wiki.

In the setting "Authorization", you can specify a username and password. If not
required, the data leave empty blank. Due to the lack of IP cameras for testing,
development of the suspended element.

The username and password are stored in an SQL file without encryption, as plain
text.

6 Start / stop communication project

To start the communication, press the button "► Run" on the upper applications
toolbar. At the start of the communication all buttons will be set to "Off".
Communications speed depends on the total number of elements and settings "Delay
between requests" in the main menu, "Global Settings".

When communication error over 3 consecutive time element is deactivated, and

will be grayed.

To see the current status of the communication, press the button "˅" under the top
panel. This opens the auxiliary panel. It contains the following items:

1. There are no active requests – did not match any item with a full set of
communication parameters.
2. Cycle № xx – number of the current communication cycle. By cycle is meant
executing requests all elements.
3. Successful: xx – the number of successful requests in the last cycle.
4. Errors: xx – the number of failed requests in the last cycle. Unsuccessful
considered a request which has not received a response within timeout or
received a response does not match expected.

If communication is not successful, you can use to analyze the function "Log"
from the main menu.

To stop communication press the button "■ Stop" on the upper application bar.
7 Log communication, error analysis

Log allows you to analyze communication error occurs in the communication

process or check requests and responses sent and received by the application.

The log contains the last 50 requests upon reaching this amount will automatically
delete old requests from the log, so that the analysis is desirable to stop the process of
communication.

Clear the log, you can using the "x" button on the top panel.

The log contains this information about the request:

1. The request to: IP address of the server: server port | PLC Address # function
modbus x register address (bits) type of request.
2. If the connection was not, then: Try to connect: the Ip address of the server:
server port.
3. Connection: the Ip address of the server: server port: the connection status.
4. If the connection is successful, will be shown in hexadecimal format request.
5. If you receive a response will be shown a response in hexadecimal format.
6. The value: is the requested value converted to the specified format.
7. If no value is received, the output value is "null"

Sample message log is shown in Figure 5.

1 request

2 request

3 request

Figure 5. Sample message log.

Figure 5 shows three requests:

1. The bit request to the server 192.168.82.125 port 8000, PLC №0, Modbus
request type 3, address: 7. Receive the value: 55.
2. The bit request to the server 127.0.0.1 port 502. Since the connection was
unsuccessful, the "null" value is obtained. In the next cycle requests will be
reconnection.
 3. Numeric request to the server 192.168.82.125 port 8000, PLC №0, Modbus
request type: 1, address 5. Receive a successful a response "true" that
corresponds to the "ON" button.

At present a new attempt is made to connect to the device when the

communication error occurs.

8 Exit the program

To quit the program press the "Back" button, and the dialog box will appear, which
prompts exit without saving, save the project, or cancel exit from the app.

After exit the user returns to the start window. In start window you can select the
desired action. When you exit the main window will automatically stop communication.

9 Project Viewer (runtime)

For the execution of projects established in app HMI Modbus created separate
application: HMI Modbus Viewer.

HMI Modbus Viewer only allows loading and execution projects created in the
main version of the program. Loading is performed only from external folders, so the
project must first be exported from the main program using the "Export" of the main
menu.

New viewer version will be available shortly after the publication of a new version
of the editor.

The viewer project provides an opportunity to set the project execution without
displaying the startup screen. If this option is selected, the communication launches when
the application starts.

Project execution program without editing options located on Google Play:

https://play.google.com/store/apps/details?id=net.sagram.hmi_modbus_viewer