SoftMC-Wiki - User contributions [en]

File:MB Required files.zip

2018-01-04T17:12:15Z

Omri: Omri uploaded a new version of "File:MB Required files.zip"

File:MB Required files.zip

2018-01-03T09:07:45Z

Omri: Omri uploaded a new version of "File:MB Required files.zip"

File:MB Required files.zip

2017-11-05T12:23:22Z

Omri: Omri uploaded a new version of "File:MB Required files.zip"

Communication

2017-11-05T12:15:16Z

Omri: /* Modbus */ removed link to old API

{{Languages}}
=LAN=
* [[IP Address|'''IP Address''']]
* [[Socket keep-alive timeouts|'''Keepalive''']]
* [[Communication/FastData|'''UDP FastData''']] 
* '''[[:File:FTPSCRN.PNG| FTP]]''' standard ftp file accesses
 
=Motion Bus=
* [[CANopen_Protocol|'''CANopen''']] - ''Functions are available since version'' SOCKCAN 0.4.11.2rc8 / CANOPEN 0.4.11.2rc8
** [[:Category:CANopen:Firmware Functions|CANopen Firmware Functions Reference]] - CANopen functions provided by firmware
** [[:Category:CANopen:Functions|CANopen Functions Reference]] - A list of CANopen functions
** [[:Category:CANOpen:Setup|CANopen Setup]] - How to setup can open network and device(s)
** [[Program_Examples:CANOpen:DS402_CAN_Drive_Setup|DS402 CAN Drive Setup]] - program example
 
*'''[[EtherCAT]]'''
** [[:Category:EtherCAT:ECAT_GENERAL_GUIDE|EtherCAT - General Guide]]
** [[:Category:EtherCAT:EC SETUP|Setup EtherCAT]] - How to setup EtherCAT
** [[:Category:EtherCAT:Functions|EtherCAT Functions Reference]] - A list of basic EtherCAT functions
** [[:Category:EtherCAT:Advanced Functions|Advanced EtherCAT Functions Reference]] - A list of advanced EtherCAT functions
** [[:EtherCAT:DIGITAL-IOS|Digital IOs]] - Associate between System Digital IOs and drives and IO Modules IOs
** [[:EtherCAT:Drive Control Bits|Drive Control Bits]] - Implementation of Drive Control Bits under EtherCAT
** [[:EtherCAT:EC_INSTALL_STX_CDHD|EC_INSTALL_STX_CDHD]] - How to configure CDHD drives
 
=Serial=
[[Serial Communication|'''Serial Communication''']]
 
=Modbus=
[[Modbus Communication API|'''Modbus Communication]]

File:MB Required files.zip

2016-12-08T08:52:11Z

Omri: Omri uploaded a new version of "File:MB Required files.zip"

File:MB Required files.zip

2016-12-05T11:54:13Z

Omri: Omri uploaded a new version of "File:MB Required files.zip"

Communication

2016-12-05T11:53:26Z

Omri: Modbus new API

'''LAN'''
* [[IP Address|'''IP Address''']]
* [[Socket keep-alive timeouts|'''Keepalive''']]
* TCP/IP Communication (''to be completed'')
** Setup
** [[Program_Examples:TCP_IP:TCPIP_Simple_Server]] Simple TCP/IP server
** [[Program_Examples:TCP_IP:TCPIP_TelNet_Server]] Simple Telnet server and command parser
** [[Program_Examples:TCP_IP:TCPIP_Simple_Client]] Simple TCP/IP client
** [[Program_Examples:TCP_IP:TCPIP_Multi_Server]] Multi client TCP/IP server
** [[Program_Examples:TCP_IP:TCPIP_Winsock_Client]] An example written in C langauge, corresponds to the [[Program_Examples:TCP_IP:TCPIP_TelNet_Server|TCP/IP TelNet Server]] example
* [[Communication/FastData|'''UDP FastData''']] 
* '''[[:File:FTPSCRN.PNG| FTP]]''' standard ftp file accesses

 

'''Automation Bus'''
* [[CANopen_Protocol|'''CANopen''']] - ''Functions are available since version'' SOCKCAN 0.4.11.2rc8 / CANOPEN 0.4.11.2rc8
** [[:Category:CANopen:Firmware Functions|CANopen Firmware Functions Reference]] - CANopen functions provided by firmware
** [[:Category:CANopen:Functions|CANopen Functions Reference]] - A list of CANopen functions
** [[:Category:CANOpen:Setup|CANopen Setup]] - How to setup can open network and device(s)
** [[Program_Examples:CANOpen:DS402_CAN_Drive_Setup|DS402 CAN Drive Setup]] - program example
 
*'''[[EtherCAT]]'''
** [[:Category:EtherCAT:ECAT_GENERAL_GUIDE|EtherCAT - General Guide]]
** [[:Category:EtherCAT:EC SETUP|Setup EtherCAT]] - How to setup EtherCAT
** [[:Category:EtherCAT:Functions|EtherCAT Functions Reference]] - A list of basic EtherCAT functions
** [[:Category:EtherCAT:Advanced Functions|Advanced EtherCAT Functions Reference]] - A list of advanced EtherCAT functions
** [[:EtherCAT:DIGITAL-IOS|Digital IOs]] - Associate between System Digital IOs and drives and IO Modules IOs
** [[:EtherCAT:Drive Control Bits|Drive Control Bits]] - Implementation of Drive Control Bits under EtherCAT
** [[:EtherCAT:EC_INSTALL_STX_CDHD|EC_INSTALL_STX_CDHD]] - How to configure CDHD drives
 
[[Serial Communication|'''Serial Communication''']]
 
[[Modbus Communication API|'''Modbus Communication]] 
[[Modbus Communication|'''Modbus Communication (Depricated)''']]
 
[[Category:Control:Offline]]

Modbus Communication API

2016-11-01T06:19:24Z

Omri:

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files: [[:File:MB_Required_files.zip]]
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Load.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Load MB_Load.prg by typing: <pre>Load MB_Load.prg</pre>
#:This will load the mb_x86.O / mb_armA9.O, depending on your current system, along with the Modbus.LIB Library file.
# '''Alternatively''', you can load the Object file and the Modbus library manually, by typing:
#:<Pre>
#::Oload mb_x86.O
#::Loadglobal Modbus.LIB</pre>

That's it! You're now ready to configure the Modbus system.

== Initializing the Modbus Environment ==
To initialize the Modbus environment, including the server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You MUST call this method even if you only need Client components. In that case, just pass 0 as the required registers' size.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== '''Adding server components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== '''Stopping Server Components''' ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== '''Adding client components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.

'''Notice:''' This function is called automatically when calling ''reset all''.

== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== '''Client Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}

=== '''Reading and Writing Summary''' ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
== Background ==
=== General ===
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access, or Write Access. Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.
=== Mapping Variables ===
* Variables destined to be mapped to Modbus tags must be defined as global variables by the '''common Shared''' declaration.
* In order to map the variables, the program must be loaded in the softMC.

== Getting Started ==
#Start the Modbus Configurator: from the ControlStudio toolbar, select '''Tools > Modbus Configurator'''. The Modbus Configurator tool will appear.
#From the top menu, Select '''Connection > Setting'''.
#'''Enter the MC's IP and port''' (default connection port is 5001), then '''click OK'''.
# From the top menu, Select '''Connection > Connect'''.
# Configure the Modbus Address Space
## From the top menu, Select '''Modbus Comm. Settings'''.
## In the '''General''' tab, Select the appropriate python script.
## In the '''Registers''' tab, enter the amount of registers needed per type, and the registers offset (Optional).
##* Notice: The maximum register number is 65536.
## In the '''Connections''' tab, add the server connections (TCP/RTU).
## Click '''OK'''.
# Map your variables
#* Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table, along with the Modbus address space area in which the data will be stored (Default: Holding Registers).
#* If a mapped variable is '''defined as CONST''', its access type will automatically set to "Read". In such instances the access type cannot be changed. "Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.
#* If a mapped variable is '''not defined as CONST''', it automatically appears with "Write" Access. '''Double-click on the access type''' to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 

==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

File:MB Required files.zip

2016-05-16T09:20:24Z

Omri: Omri uploaded a new version of "File:MB Required files.zip"

File:MB Required files.zip

2016-05-08T08:05:52Z

Omri: Omri uploaded a new version of "File:MB Required files.zip"

Modbus Communication API

2016-05-03T13:28:12Z

Omri: /* Reset the Modbus System */ Added a note

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files: [[:File:MB_Required_files.zip]]
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Load.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Load MB_Load.prg by typing: <pre>Load MB_Load.prg</pre>
#:This will load the mb_x86.O / mb_armA9.O, depending on your current system, along with the Modbus.LIB Library file.
# '''Alternatively''', you can load the Object file and the Modbus library manually, by typing:
#:<Pre>
#::Oload mb_x86.O
#::Loadglobal Modbus.LIB</pre>

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== '''Adding server components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== '''Stopping Server Components''' ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== '''Adding client components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.

'''Notice:''' This function is called automatically when calling ''reset all''.

== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== '''Client Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}

=== '''Reading and Writing Summary''' ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
== Background ==
=== General ===
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access, or Write Access. Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.
=== Mapping Variables ===
* Variables destined to be mapped to Modbus tags must be defined as global variables by the '''common Shared''' declaration.
* In order to map the variables, the program must be loaded in the softMC.

== Getting Started ==
#Start the Modbus Configurator: from the ControlStudio toolbar, select '''Tools > Modbus Configurator'''. The Modbus Configurator tool will appear.
#From the top menu, Select '''Connection > Setting'''.
#'''Enter the MC's IP and port''' (default connection port is 5001), then '''click OK'''.
# From the top menu, Select '''Connection > Connect'''.
# Configure the Modbus Address Space
## From the top menu, Select '''Modbus Comm. Settings'''.
## In the '''General''' tab, Select the appropriate python script.
## In the '''Registers''' tab, enter the amount of registers needed per type, and the registers offset (Optional).
##* Notice: The maximum register number is 65536.
## In the '''Connections''' tab, add the server connections (TCP/RTU).
## Click '''OK'''.
# Map your variables
#* Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table, along with the Modbus address space area in which the data will be stored (Default: Holding Registers).
#* If a mapped variable is '''defined as CONST''', its access type will automatically set to "Read". In such instances the access type cannot be changed. "Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.
#* If a mapped variable is '''not defined as CONST''', it automatically appears with "Write" Access. '''Double-click on the access type''' to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 

==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-05-02T08:00:16Z

Omri: updated link to required files

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files: [[:File:MB_Required_files.zip]]
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Load.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Load MB_Load.prg by typing: <pre>Load MB_Load.prg</pre>
#:This will load the mb_x86.O / mb_armA9.O, depending on your current system, along with the Modbus.LIB Library file.
# '''Alternatively''', you can load the Object file and the Modbus library manually, by typing:
#:<Pre>
#::Oload mb_x86.O
#::Loadglobal Modbus.LIB</pre>

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== '''Adding server components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== '''Stopping Server Components''' ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== '''Adding client components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== '''Client Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}

=== '''Reading and Writing Summary''' ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
== Background ==
=== General ===
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access, or Write Access. Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.
=== Mapping Variables ===
* Variables destined to be mapped to Modbus tags must be defined as global variables by the '''common Shared''' declaration.
* In order to map the variables, the program must be loaded in the softMC.

== Getting Started ==
#Start the Modbus Configurator: from the ControlStudio toolbar, select '''Tools > Modbus Configurator'''. The Modbus Configurator tool will appear.
#From the top menu, Select '''Connection > Setting'''.
#'''Enter the MC's IP and port''' (default connection port is 5001), then '''click OK'''.
# From the top menu, Select '''Connection > Connect'''.
# Configure the Modbus Address Space
## From the top menu, Select '''Modbus Comm. Settings'''.
## In the '''General''' tab, Select the appropriate python script.
## In the '''Registers''' tab, enter the amount of registers needed per type, and the registers offset (Optional).
##* Notice: The maximum register number is 65536.
## In the '''Connections''' tab, add the server connections (TCP/RTU).
## Click '''OK'''.
# Map your variables
#* Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table, along with the Modbus address space area in which the data will be stored (Default: Holding Registers).
#* If a mapped variable is '''defined as CONST''', its access type will automatically set to "Read". In such instances the access type cannot be changed. "Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.
#* If a mapped variable is '''not defined as CONST''', it automatically appears with "Write" Access. '''Double-click on the access type''' to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 

==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

File:MB Required files.zip

2016-05-02T07:55:37Z

Omri: -> Creation failed: Unsupported filetype!

Modbus Communication API

2016-05-02T07:20:20Z

Omri: /* Getting Started */

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Load.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Load MB_Load.prg by typing: <pre>Load MB_Load.prg</pre>
#:This will load the mb_x86.O / mb_armA9.O, depending on your current system, along with the Modbus.LIB Library file.
# '''Alternatively''', you can load the Object file and the Modbus library manually, by typing:
#:<Pre>
#::Oload mb_x86.O
#::Loadglobal Modbus.LIB</pre>

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== '''Adding server components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== '''Stopping Server Components''' ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== '''Adding client components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== '''Client Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}

=== '''Reading and Writing Summary''' ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
== Background ==
=== General ===
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access, or Write Access. Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.
=== Mapping Variables ===
* Variables destined to be mapped to Modbus tags must be defined as global variables by the '''common Shared''' declaration.
* In order to map the variables, the program must be loaded in the softMC.

== Getting Started ==
#Start the Modbus Configurator: from the ControlStudio toolbar, select '''Tools > Modbus Configurator'''. The Modbus Configurator tool will appear.
#From the top menu, Select '''Connection > Setting'''.
#'''Enter the MC's IP and port''' (default connection port is 5001), then '''click OK'''.
# From the top menu, Select '''Connection > Connect'''.
# Configure the Modbus Address Space
## From the top menu, Select '''Modbus Comm. Settings'''.
## In the '''General''' tab, Select the appropriate python script.
## In the '''Registers''' tab, enter the amount of registers needed per type, and the registers offset (Optional).
##* Notice: The maximum register number is 65536.
## In the '''Connections''' tab, add the server connections (TCP/RTU).
## Click '''OK'''.
# Map your variables
#* Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table, along with the Modbus address space area in which the data will be stored (Default: Holding Registers).
#* If a mapped variable is '''defined as CONST''', its access type will automatically set to "Read". In such instances the access type cannot be changed. "Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.
#* If a mapped variable is '''not defined as CONST''', it automatically appears with "Write" Access. '''Double-click on the access type''' to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 

==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-05-02T06:53:57Z

Omri: /* Getting Started */

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Load.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Load MB_Load.prg by typing: <pre>Load MB_Load.prg</pre>
#:This will load the mb_x86.O / mb_armA9.O, depending on your current system, along with the Modbus.LIB Library file.
# '''Alternatively''', you can load the Object file and the Modbus library manually, by typing: <pre>Oload mb_x86.O
#: Loadglobal Modbus.LIB</pre>.

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== '''Adding server components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== '''Stopping Server Components''' ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== '''Adding client components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== '''Client Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}

=== '''Reading and Writing Summary''' ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
== Background ==
=== General ===
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access, or Write Access. Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.
=== Mapping Variables ===
* Variables destined to be mapped to Modbus tags must be defined as global variables by the '''common Shared''' declaration.
* In order to map the variables, the program must be loaded in the softMC.

== Getting Started ==
#Start the Modbus Configurator: from the ControlStudio toolbar, select '''Tools > Modbus Configurator'''. The Modbus Configurator tool will appear.
#From the top menu, Select '''Connection > Setting'''.
#'''Enter the MC's IP and port''' (default connection port is 5001), then '''click OK'''.
# From the top menu, Select '''Connection > Connect'''.
# Configure the Modbus Address Space
## From the top menu, Select '''Modbus Comm. Settings'''.
## In the '''General''' tab, Select the appropriate python script.
## In the '''Registers''' tab, enter the amount of registers needed per type, and the registers offset (Optional).
##* Notice: The maximum register number is 65536.
## In the '''Connections''' tab, add the server connections (TCP/RTU).
## Click '''OK'''.
# Map your variables
#* Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table, along with the Modbus address space area in which the data will be stored (Default: Holding Registers).
#* If a mapped variable is '''defined as CONST''', its access type will automatically set to "Read". In such instances the access type cannot be changed. "Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.
#* If a mapped variable is '''not defined as CONST''', it automatically appears with "Write" Access. '''Double-click on the access type''' to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 

==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-05-02T06:48:26Z

Omri: /* Getting Started */ Added instructions for automaed/manual load of the shared object

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Load.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Load MB_Load.prg by typing: <pre>Load MB_Load.prg</pre>
#:This will load the mb_x86.O / mb_armA9.O, depending on your current system.
# '''Alternatively''', you can load the Object file manually by typing: <pre>Oload mb_x86.O</pre>.

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== '''Adding server components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== '''Stopping Server Components''' ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== '''Adding client components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== '''Client Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}

=== '''Reading and Writing Summary''' ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
== Background ==
=== General ===
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access, or Write Access. Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.
=== Mapping Variables ===
* Variables destined to be mapped to Modbus tags must be defined as global variables by the '''common Shared''' declaration.
* In order to map the variables, the program must be loaded in the softMC.

== Getting Started ==
#Start the Modbus Configurator: from the ControlStudio toolbar, select '''Tools > Modbus Configurator'''. The Modbus Configurator tool will appear.
#From the top menu, Select '''Connection > Setting'''.
#'''Enter the MC's IP and port''' (default connection port is 5001), then '''click OK'''.
# From the top menu, Select '''Connection > Connect'''.
# Configure the Modbus Address Space
## From the top menu, Select '''Modbus Comm. Settings'''.
## In the '''General''' tab, Select the appropriate python script.
## In the '''Registers''' tab, enter the amount of registers needed per type, and the registers offset (Optional).
##* Notice: The maximum register number is 65536.
## In the '''Connections''' tab, add the server connections (TCP/RTU).
## Click '''OK'''.
# Map your variables
#* Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table, along with the Modbus address space area in which the data will be stored (Default: Holding Registers).
#* If a mapped variable is '''defined as CONST''', its access type will automatically set to "Read". In such instances the access type cannot be changed. "Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.
#* If a mapped variable is '''not defined as CONST''', it automatically appears with "Write" Access. '''Double-click on the access type''' to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 

==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-05-02T06:36:36Z

Omri: /* Getting Started */ Added instructions for the new Modbus Comm. Settings window.

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Loader.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Run MB_Loader.prg

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== '''Adding server components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== '''Stopping Server Components''' ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== '''Adding client components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== '''Client Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}

=== '''Reading and Writing Summary''' ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
== Background ==
=== General ===
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access, or Write Access. Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.
=== Mapping Variables ===
* Variables destined to be mapped to Modbus tags must be defined as global variables by the '''common Shared''' declaration.
* In order to map the variables, the program must be loaded in the softMC.

== Getting Started ==
#Start the Modbus Configurator: from the ControlStudio toolbar, select '''Tools > Modbus Configurator'''. The Modbus Configurator tool will appear.
#From the top menu, Select '''Connection > Setting'''.
#'''Enter the MC's IP and port''' (default connection port is 5001), then '''click OK'''.
# From the top menu, Select '''Connection > Connect'''.
# Configure the Modbus Address Space
## From the top menu, Select '''Modbus Comm. Settings'''.
## In the '''General''' tab, Select the appropriate python script.
## In the '''Registers''' tab, enter the amount of registers needed per type, and the registers offset (Optional).
##* Notice: The maximum register number is 65536.
## In the '''Connections''' tab, add the server connections (TCP/RTU).
## Click '''OK'''.
# Map your variables
#* Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table, along with the Modbus address space area in which the data will be stored (Default: Holding Registers).
#* If a mapped variable is '''defined as CONST''', its access type will automatically set to "Read". In such instances the access type cannot be changed. "Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.
#* If a mapped variable is '''not defined as CONST''', it automatically appears with "Write" Access. '''Double-click on the access type''' to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 

==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-05-02T06:20:32Z

Omri: /* Modbus Configurator */ Updated with new configurator options

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Loader.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Run MB_Loader.prg

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== '''Adding server components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== '''Stopping Server Components''' ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== '''Adding client components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== '''Client Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}

=== '''Reading and Writing Summary''' ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
== Background ==
=== General ===
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access, or Write Access. Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.
=== Mapping Variables ===
* Variables destined to be mapped to Modbus tags must be defined as global variables by the '''common Shared''' declaration.
* In order to map the variables, the program must be loaded in the softMC.

== Getting Started ==
#Start the Modbus Configurator: from the ControlStudio toolbar, select '''Tools > Modbus Configurator'''. The Modbus Configurator tool will appear.
#From the top menu, Select '''Connection > Setting'''.
#'''Enter the MC's IP and port''' (default connection port is 5001), then '''click OK'''.
# From the top menu, Select '''Connection > Connect'''.

Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table, along with the Modbus address space area in which the data will be stored (Default: Holding Registers).

* If a mapped variable is '''defined as CONST''', its access type will automatically set to "Read". In such instances the access type cannot be changed. "Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.

* If a mapped variable is '''not defined as CONST''', it automatically appears with "Write" Access. '''Double-click on the access type''' to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 
==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-04-18T13:42:43Z

Omri: minor formatting changes

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Loader.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Run MB_Loader.prg

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== '''Adding server components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== '''Stopping Server Components''' ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== '''Adding client components''' ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== '''Client Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}

=== '''Reading and Writing Summary''' ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access (meaning it is read by the HMI/PLC), or Write Access (meaning it is written by the HMI/PLC). Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.

== Mapping Variables==
'''Note''': Variables destined to be mapped to Modbus tags must be defined as global variables by the Common Shared declaration.

1. In order to map the variables, the program must be loaded in the softMC.

2. Start the Modbus Configuration: from the ControlStudio toolbar, select Tools, and then Modbus Configurator…

:The Modbus Configurator windows opens.

3. Click Connection, and select Setting.

:The setting dialog box opens, with fields showing the following (default) settings:

[[File:softMC_Modbus_HMI_(3).png|600px]]
 
 
* Modbus offset: Used to start the mapping from an address other than zero.
* Script file name: A Python script that generates the product files. Different scripts create different .csv files.
* Output LIB, Output Prog, HMI CSV file name: Used to define target file names.
:'''Note''': The softMC file names must be UPPERCASE and in 8.3 format.
* MC IP address: Used to set the IP address of your softMC.
Make any necessary changes in the Settings dialog box. Then click Connection, and then Connect.

Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table.

If a mapped variable is defined as CONST, its access type is automatically set to Read. In such instances the access type cannot be changed. Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.

A variable that is not defined as CONST automatically appears as Write Access. Double-click on the access type to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 
==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-04-18T13:38:28Z

Omri: /* Client Components */

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Loader.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Run MB_Loader.prg

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== Adding server components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== Stopping Server Components ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== Adding client components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== '''Client Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}

=== Reading and Writing Summary ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access (meaning it is read by the HMI/PLC), or Write Access (meaning it is written by the HMI/PLC). Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.

== Mapping Variables==
'''Note''': Variables destined to be mapped to Modbus tags must be defined as global variables by the Common Shared declaration.

1. In order to map the variables, the program must be loaded in the softMC.

2. Start the Modbus Configuration: from the ControlStudio toolbar, select Tools, and then Modbus Configurator…

:The Modbus Configurator windows opens.

3. Click Connection, and select Setting.

:The setting dialog box opens, with fields showing the following (default) settings:

[[File:softMC_Modbus_HMI_(3).png|600px]]
 
 
* Modbus offset: Used to start the mapping from an address other than zero.
* Script file name: A Python script that generates the product files. Different scripts create different .csv files.
* Output LIB, Output Prog, HMI CSV file name: Used to define target file names.
:'''Note''': The softMC file names must be UPPERCASE and in 8.3 format.
* MC IP address: Used to set the IP address of your softMC.
Make any necessary changes in the Settings dialog box. Then click Connection, and then Connect.

Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table.

If a mapped variable is defined as CONST, its access type is automatically set to Read. In such instances the access type cannot be changed. Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.

A variable that is not defined as CONST automatically appears as Write Access. Double-click on the access type to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 
==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-04-18T13:37:48Z

Omri: /* Server Components */

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Loader.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Run MB_Loader.prg

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== Adding server components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== Stopping Server Components ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== Adding client components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== '''Server Components''' ===
<hr>
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}

=== Client Components ===
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}
=== Reading and Writing Summary ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access (meaning it is read by the HMI/PLC), or Write Access (meaning it is written by the HMI/PLC). Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.

== Mapping Variables==
'''Note''': Variables destined to be mapped to Modbus tags must be defined as global variables by the Common Shared declaration.

1. In order to map the variables, the program must be loaded in the softMC.

2. Start the Modbus Configuration: from the ControlStudio toolbar, select Tools, and then Modbus Configurator…

:The Modbus Configurator windows opens.

3. Click Connection, and select Setting.

:The setting dialog box opens, with fields showing the following (default) settings:

[[File:softMC_Modbus_HMI_(3).png|600px]]
 
 
* Modbus offset: Used to start the mapping from an address other than zero.
* Script file name: A Python script that generates the product files. Different scripts create different .csv files.
* Output LIB, Output Prog, HMI CSV file name: Used to define target file names.
:'''Note''': The softMC file names must be UPPERCASE and in 8.3 format.
* MC IP address: Used to set the IP address of your softMC.
Make any necessary changes in the Settings dialog box. Then click Connection, and then Connect.

Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table.

If a mapped variable is defined as CONST, its access type is automatically set to Read. In such instances the access type cannot be changed. Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.

A variable that is not defined as CONST automatically appears as Write Access. Double-click on the access type to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 
==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-04-18T13:26:27Z

Omri: /* Initializing a Modbus Server */

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Loader.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Run MB_Loader.prg

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:''' You can call this method only if there are no active server components.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== Adding server components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== Stopping Server Components ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== Adding client components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== Server Components ===
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}
=== Client Components ===
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}
=== Reading and Writing Summary ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access (meaning it is read by the HMI/PLC), or Write Access (meaning it is written by the HMI/PLC). Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.

== Mapping Variables==
'''Note''': Variables destined to be mapped to Modbus tags must be defined as global variables by the Common Shared declaration.

1. In order to map the variables, the program must be loaded in the softMC.

2. Start the Modbus Configuration: from the ControlStudio toolbar, select Tools, and then Modbus Configurator…

:The Modbus Configurator windows opens.

3. Click Connection, and select Setting.

:The setting dialog box opens, with fields showing the following (default) settings:

[[File:softMC_Modbus_HMI_(3).png|600px]]
 
 
* Modbus offset: Used to start the mapping from an address other than zero.
* Script file name: A Python script that generates the product files. Different scripts create different .csv files.
* Output LIB, Output Prog, HMI CSV file name: Used to define target file names.
:'''Note''': The softMC file names must be UPPERCASE and in 8.3 format.
* MC IP address: Used to set the IP address of your softMC.
Make any necessary changes in the Settings dialog box. Then click Connection, and then Connect.

Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table.

If a mapped variable is defined as CONST, its access type is automatically set to Read. In such instances the access type cannot be changed. Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.

A variable that is not defined as CONST automatically appears as Write Access. Double-click on the access type to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 
==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-04-18T13:23:42Z

Omri: /* Getting Started */

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Loader.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Run MB_Loader.prg

That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:'''
*# This is '''NOT''' required when softMC does not run a modbus server.
*# You can call this method only if no servers are running.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== Adding server components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== Stopping Server Components ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== Adding client components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== Server Components ===
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}
=== Client Components ===
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}
=== Reading and Writing Summary ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access (meaning it is read by the HMI/PLC), or Write Access (meaning it is written by the HMI/PLC). Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.

== Mapping Variables==
'''Note''': Variables destined to be mapped to Modbus tags must be defined as global variables by the Common Shared declaration.

1. In order to map the variables, the program must be loaded in the softMC.

2. Start the Modbus Configuration: from the ControlStudio toolbar, select Tools, and then Modbus Configurator…

:The Modbus Configurator windows opens.

3. Click Connection, and select Setting.

:The setting dialog box opens, with fields showing the following (default) settings:

[[File:softMC_Modbus_HMI_(3).png|600px]]
 
 
* Modbus offset: Used to start the mapping from an address other than zero.
* Script file name: A Python script that generates the product files. Different scripts create different .csv files.
* Output LIB, Output Prog, HMI CSV file name: Used to define target file names.
:'''Note''': The softMC file names must be UPPERCASE and in 8.3 format.
* MC IP address: Used to set the IP address of your softMC.
Make any necessary changes in the Settings dialog box. Then click Connection, and then Connect.

Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table.

If a mapped variable is defined as CONST, its access type is automatically set to Read. In such instances the access type cannot be changed. Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.

A variable that is not defined as CONST automatically appears as Write Access. Double-click on the access type to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 
==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-04-18T13:23:21Z

Omri: /* Getting Started */

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
#* Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
#* Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
#* mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
#* Modbus.lib
#* MB_Loader.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Run MB_Loader.prg
# That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:'''
*# This is '''NOT''' required when softMC does not run a modbus server.
*# You can call this method only if no servers are running.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== Adding server components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== Stopping Server Components ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== Adding client components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== Server Components ===
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}
=== Client Components ===
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}
=== Reading and Writing Summary ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access (meaning it is read by the HMI/PLC), or Write Access (meaning it is written by the HMI/PLC). Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.

== Mapping Variables==
'''Note''': Variables destined to be mapped to Modbus tags must be defined as global variables by the Common Shared declaration.

1. In order to map the variables, the program must be loaded in the softMC.

2. Start the Modbus Configuration: from the ControlStudio toolbar, select Tools, and then Modbus Configurator…

:The Modbus Configurator windows opens.

3. Click Connection, and select Setting.

:The setting dialog box opens, with fields showing the following (default) settings:

[[File:softMC_Modbus_HMI_(3).png|600px]]
 
 
* Modbus offset: Used to start the mapping from an address other than zero.
* Script file name: A Python script that generates the product files. Different scripts create different .csv files.
* Output LIB, Output Prog, HMI CSV file name: Used to define target file names.
:'''Note''': The softMC file names must be UPPERCASE and in 8.3 format.
* MC IP address: Used to set the IP address of your softMC.
Make any necessary changes in the Settings dialog box. Then click Connection, and then Connect.

Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table.

If a mapped variable is defined as CONST, its access type is automatically set to Read. In such instances the access type cannot be changed. Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.

A variable that is not defined as CONST automatically appears as Write Access. Double-click on the access type to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 
==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

File:modbus;newAPI-upload.jpg

2016-04-18T13:21:41Z

Omri: -> Creation failed: Unsupported filetype!

Modbus Communication API

2016-04-18T11:40:40Z

Omri: /* Getting Started */

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
## Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
## Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
## mb_x86.O ''(for softMC7 )'' / mb_armA9.O ''(for softMC3)''
## Modbus.lib
## MB_Loader.prg
#:[[File:modbus;newAPI-upload.jpg|850px]]
# Load (Run) MB_Loader.prg
# Use the ControlStudio Terminal to enter the following:
#:<pre>
#::reset all
#::?tasklist</pre>
#: The system's response: <pre>GlobalLibraryName=MODBUS.LIB</pre>
#:This indicates that library MODBUS.LIB has been loaded globally.
#:[[File:softMC_Modbus_HMI_(2).png|300px]]
# That's it! You're now ready to configure the Modbus system.

== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:'''
*# This is '''NOT''' required when softMC does not run a modbus server.
*# You can call this method only if no servers are running.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== Adding server components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== Stopping Server Components ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== Adding client components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== Server Components ===
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}
=== Client Components ===
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}
=== Reading and Writing Summary ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access (meaning it is read by the HMI/PLC), or Write Access (meaning it is written by the HMI/PLC). Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.

== Mapping Variables==
'''Note''': Variables destined to be mapped to Modbus tags must be defined as global variables by the Common Shared declaration.

1. In order to map the variables, the program must be loaded in the softMC.

2. Start the Modbus Configuration: from the ControlStudio toolbar, select Tools, and then Modbus Configurator…

:The Modbus Configurator windows opens.

3. Click Connection, and select Setting.

:The setting dialog box opens, with fields showing the following (default) settings:

[[File:softMC_Modbus_HMI_(3).png|600px]]
 
 
* Modbus offset: Used to start the mapping from an address other than zero.
* Script file name: A Python script that generates the product files. Different scripts create different .csv files.
* Output LIB, Output Prog, HMI CSV file name: Used to define target file names.
:'''Note''': The softMC file names must be UPPERCASE and in 8.3 format.
* MC IP address: Used to set the IP address of your softMC.
Make any necessary changes in the Settings dialog box. Then click Connection, and then Connect.

Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table.

If a mapped variable is defined as CONST, its access type is automatically set to Read. In such instances the access type cannot be changed. Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.

A variable that is not defined as CONST automatically appears as Write Access. Double-click on the access type to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 
==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

File:modbus;newAPI-readwriteSummary.jpg

2016-04-18T11:27:49Z

Omri: -> Creation failed: Unsupported filetype!

Modbus Communication API

2016-04-17T07:45:51Z

Omri: /* 4 HMI IDEs and .CSV Files */

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
## Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
## Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
## mb_x86.O ''(for X86 Systems)'' / mb_armA9.O ''(for ARM Systems)''
## Modbus.lib
#* '''Notice:''' From now on, in our examples, we'll use the X86 configuration. [[File:modbus;newAPI-upload.jpg|850px]]
# Access the file CONFIG.PRG and modify the program by adding the following two lines:
#:<pre>
#::Program
#:: Oload mb_x86.O
#:: Load modbus.lib
#::...
#::...
#::End Program</pre>
# Upload CONFIG.PRG to the softMC.
# Use the ControlStudio Terminal to enter the following:
#:<pre>
#::reset all
#::?tasklist</pre>
#: The system's response: <pre>GlobalLibraryName=MODBUS.LIB</pre>
#:This indicates that library MODBUS.LIB has been loaded globally.
#:[[File:softMC_Modbus_HMI_(2).png|300px]]
# That's it! You're now ready to configure the Modbus system.
== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:'''
*# This is '''NOT''' required when softMC does not run a modbus server.
*# You can call this method only if no servers are running.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== Adding server components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== Stopping Server Components ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== Adding client components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== Server Components ===
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}
=== Client Components ===
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}
=== Reading and Writing Summary ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access (meaning it is read by the HMI/PLC), or Write Access (meaning it is written by the HMI/PLC). Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.

== Mapping Variables==
'''Note''': Variables destined to be mapped to Modbus tags must be defined as global variables by the Common Shared declaration.

1. In order to map the variables, the program must be loaded in the softMC.

2. Start the Modbus Configuration: from the ControlStudio toolbar, select Tools, and then Modbus Configurator…

:The Modbus Configurator windows opens.

3. Click Connection, and select Setting.

:The setting dialog box opens, with fields showing the following (default) settings:

[[File:softMC_Modbus_HMI_(3).png|600px]]
 
 
* Modbus offset: Used to start the mapping from an address other than zero.
* Script file name: A Python script that generates the product files. Different scripts create different .csv files.
* Output LIB, Output Prog, HMI CSV file name: Used to define target file names.
:'''Note''': The softMC file names must be UPPERCASE and in 8.3 format.
* MC IP address: Used to set the IP address of your softMC.
Make any necessary changes in the Settings dialog box. Then click Connection, and then Connect.

Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table.

If a mapped variable is defined as CONST, its access type is automatically set to Read. In such instances the access type cannot be changed. Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.

A variable that is not defined as CONST automatically appears as Write Access. Double-click on the access type to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 
==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-04-17T07:43:52Z

Omri: Copied sections 8 and 9 from the previous version of the Wiki page

== Overview ==
=== Basic Overview ===
* This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
* It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
* It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as one server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* There are 4 types of registers in the Modbus Server address space:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Download the required files, according to your system's type:
## Required files for [[File:modbus_requiredFiles_x86.zip|modbus_X86.ZIP]].
## Required files for ARM systems.
# Using the ControlStudio File Manager, Upload the following files to your MC:
## mb_x86.O ''(for X86 Systems)'' / mb_armA9.O ''(for ARM Systems)''
## Modbus.lib
#* '''Notice:''' From now on, in our examples, we'll use the X86 configuration. [[File:modbus;newAPI-upload.jpg|850px]]
# Access the file CONFIG.PRG and modify the program by adding the following two lines:
#:<pre>
#::Program
#:: Oload mb_x86.O
#:: Load modbus.lib
#::...
#::...
#::End Program</pre>
# Upload CONFIG.PRG to the softMC.
# Use the ControlStudio Terminal to enter the following:
#:<pre>
#::reset all
#::?tasklist</pre>
#: The system's response: <pre>GlobalLibraryName=MODBUS.LIB</pre>
#:This indicates that library MODBUS.LIB has been loaded globally.
#:[[File:softMC_Modbus_HMI_(2).png|300px]]
# That's it! You're now ready to configure the Modbus system.
== Initializing a Modbus Server ==
To initialize the Modbus server address space, call:
<pre>?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:'''
*# This is '''NOT''' required when softMC does not run a modbus server.
*# You can call this method only if no servers are running.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Memory allocation failure.
|-
| -2
| Some servers are still running and using an already mapped address space.
|-
| -3
| Failed to create a modbus mapping.
|}

== Server Components ==
=== Adding server components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Failed to create main socket.
|-
| -3
| Failed to connect.
|-
| -4
| Failed to create server thread.
|}
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
'''Error codes:'''
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Server address spaces isn't initialized yet, please call "init_multi_server(...) and try again.
|-
| -2
| Invalid device string.
|-
| -3
| Invalid parity.
|-
| -4
| Failed opening RTU.
|-
| -5
| Failed allocating query buffer memory.
|-
| -6
| Failed to set RTU mode.
|-
| -7
| Unable to connect.
|-
| -8
| Failed to create server thread.
|-
| -9
| The device is already in use by another system component.
|}
=== Stopping Server Components ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.
== Client Components ==
=== Adding client components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.
== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.
== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== Server Components ===
==== Reading ====
* The following functions read variables from the different types of registers and return them.
* When a read error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_REG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_REG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([index])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_SHORT([index], [byte_swap])
Val = MB_SERVER_READ_INREG_FLOAT([index], [byte_swap], [word_swap])
Val = MB_SERVER_READ_INREG_DOUBLE([index], [byte_swap], [word_swap], [long swap])
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([index])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Writing ====
* The following functions write data into the different types of registers.
* When a write error occurs, the functions will write [function name] + "ERROR" + [error code] in the Message Log.
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_REG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_REG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([index],[new value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_SHORT([index],[new value],[byte swap])
Val = MB_SERVER_WRITE_INREG_FLOAT([index],[new value],[byte swap], [word swap])
Val = MB_SERVER_WRITE_INREG_DOUBLE([index],[new value],[byte swap], [word swap], [long swap])
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([index],[value])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Index
| From 0 to the number of registers available.
|-
| New value
| The value to write, must be from the appropriate type.
|-
| Byte_swap
| 1 or 0 (True/False)
|-
| Word_swap
| 1 or 0 (True/False)
|-
| Long_swap
| 1 or 0 (True/False)
|}
==== Error codes ====
{| class="wikitable" border="1"
|-
! Error
! Meaning
|-
| -1
| Invalid index.
|-
| -2
| Local server's address space isn't mapped yet.
|-
| -3
| Failed to catch the register mutex.
|-
| -4
| Failed to release the register mutex.
|}
=== Client Components ===
==== Reading ====
* The following functions read variables from the different types of registers in a REMOTE modbus server.
* The read value is inserted into an existing variable from the appropriate type (long/double).
* The functions return 0 on success or an error code (not 0) on failure.
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_FLOAT([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_DOUBLE([handle],[deviceID],[addr],[dest ptr])
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to read from.
|-
| Num of bits (Reading bits)
| The number of bits to read.
|-
| dest ptr / dest arr ptr
| The variable to store the read data. When reading bits, this must be an array of longs in the appropriate size (>= Num of bits).
|}
==== Writing ====
* The following functions write data from existing variables to the different types of registers in a REMOTE modbus server.
* The functions return 0 on success or an error code (not 0) on failure.
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_SHORT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_FLOAT([handle],[deviceID],[addr],[src ptr])
Val = MB_CLIENT_WRITE_REG_DOUBLE([handle],[deviceID],[addr],[src ptr])
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([handle],[deviceID],[addr],[src ptr])</pre>
===== Valid Parameters =====
{| class="wikitable" border="1"
|-
! Parameter
! Valid Input
|-
| Handle
| The client's unique identifier (received on client creation).
|-
| DeviceID
| The remote server(slave)'s device ID.
|-
| Addr
| The index of the register to start writing to.
|-
| src ptr
| The variable that stores the data to be written. This must be a variable from the appropriate type.
|}
=== Reading and Writing Summary ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

=Modbus Configurator=
The Modbus Communication Scripts Generator ('''Modbus Configurator''') is a tool that allows you to map your softMC application variables to Modbus tags.

'''Note''': Tag access is defined from the HMI perspective. In other words:
* '''Read Access''' variables are written by the softMC to the Modbus address space.
* '''Write Access''' variables are read by the softMC from the Modbus address space.

You can define whether a variable has Read Access (meaning it is read by the HMI/PLC), or Write Access (meaning it is written by the HMI/PLC). Currently, it is not possible to define a variable as having both Read Access and Write Access. However, all Write Access variables can be written once by the softMC upon system startup by a special routine that is generated in HMIMBMAP.LIB (see section below).

The MCMBConfigurator creates three files:
* '''HMIMBMAP.LIB''' and '''HMIMBMAP.PRG''' files are MC-Basic scripts that are used to start a softMC task. These are default file names, which you can change, but must retain the 8.3 format. This task cyclically and indefinitely reads/writes Modbus tags according to access type.
* A '''.CSV''' format file that can be used by an HMI development environment, such as '''JMobile Studio''' or '''Indusoft''', to automatically import Modbus tags. You define the HMI development environment by selecting various Python scripts that will generate the .csv file.

== Mapping Variables==
'''Note''': Variables destined to be mapped to Modbus tags must be defined as global variables by the Common Shared declaration.

1. In order to map the variables, the program must be loaded in the softMC.

2. Start the Modbus Configuration: from the ControlStudio toolbar, select Tools, and then Modbus Configurator…

:The Modbus Configurator windows opens.

3. Click Connection, and select Setting.

:The setting dialog box opens, with fields showing the following (default) settings:

[[File:softMC_Modbus_HMI_(3).png|600px]]
 
 
* Modbus offset: Used to start the mapping from an address other than zero.
* Script file name: A Python script that generates the product files. Different scripts create different .csv files.
* Output LIB, Output Prog, HMI CSV file name: Used to define target file names.
:'''Note''': The softMC file names must be UPPERCASE and in 8.3 format.
* MC IP address: Used to set the IP address of your softMC.
Make any necessary changes in the Settings dialog box. Then click Connection, and then Connect.

Once the Modbus Configurator is connected to softMC it gets updated with the complete list of all the global variables. Double-clicking on variables automatically maps them to Modbus tags in consecutive order. The automatic Modbus address and data type are displayed in the table.

If a mapped variable is defined as CONST, its access type is automatically set to Read. In such instances the access type cannot be changed. Read Access variables are read only by the HMI; therefore the softMC only writes them to the Modbus address space.

A variable that is not defined as CONST automatically appears as Write Access. Double-click on the access type to toggle the variable between Read Access and Write Access, and thus determine whether the variable will be read or written by softMC.

[[File:softMC_Modbus_HMI_(4).png|600px]]
 
 
==Generating and Using Scripts==
After you are done mapping variables and defining the access types, a snapshot of the current configuration must be saved in order to generate the Modbus-handling scripts.

1. Click '''Files''', and then '''Save As'''.

:The mapping is saved in an '''.mbas''' file.

:If you makes changes after saving the .mbas file, the MBAS file indicator in the status bar will light up.

2. To generate the product files, click '''Generate'''.

:The Log windows will display Success messages.

:The product files were created in the target folder you chose when saving the .mbas file.

:The files HMIMBMAP.LIB and HMIMBMAP.PRG will automatically open in ControlStudio.

[[File:softMC_Modbus_HMI_(5).png|600px]]

==Using the Modbus-Handling Scripts==
1. Using the ControlStudio File Manager, copy HMIMBMAP.LIB and HMIMBMAP.PRG to the softMC.

'''Note''': Before these files can be loaded and used, your application must be loaded, and all mapped variables must exist in the softMC memory.

[[File:softMC_Modbus_HMI_(6).png|600px]]
 
 
1. Using the ControlStudio Terminal, load the library HMIMBMAP.LIB:
<pre>Load HMIMBMAP.LIB</pre>

:Since HMIMBMAP.PRG imports this library it must not be loaded globally. This code can be executed wherever is convenient.

2. Verify that the library was loaded successfully:

<pre>?tasklist</pre>

3. Start the Modbus communication task by loading the program:

<pre>Load HMIMBMAP.PRG</pre>

HMIMBMAP.PRG is defined as '''Program Continue''', therefore it starts automatically after it is loaded and it does not require an explicit StartTask command.

Of course, HMIMBMAP.PRG can be loaded and executed only after HMIMBMAP.LIB is loaded. Therefore, you should add the following code to AUTOEXEC.PRG or wherever is convenient:
<pre>Load HMIMBMAP.LIB
Load HMIMBMAP.PRG
</pre>

==HMIMBMAP.PRG Explained==
The code:
<pre>import HMIMBMAP.LIB
Program Continue
dim retVal as long = 0
retVal = Init_Modbus
while 1
retVal = Read_Modbus_Registers
retVal = Write_Modbus_Registers
sleep 1
end while
End Program</pre>

The functions '''Init_Modbus''', '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are implemented in '''HMIMBMAP.LIB''', which is automatically generated by a Python script.

The function '''Init_Modbus''' starts the Modbus server and then writes to the Modbus address space all the '''Write Access Variables''' (i.e., all the variables read by the softMC from the Modbus address space). This feature allows you to setup the system to start with an initialized Modbus address space before the HMI/PLC connects to it. The HMI/PLC can read the address space and initialize itself accordingly.

The functions '''Read_Modbus_Registers''' and '''Write_Modbus_Registers''' are invoked cyclically and indefinitely. '''Read_Modbus_Registers''' reads all the tags that are written by the HMI/PLC and updates the '''Write Access''' variables with new values, while '''Write_Modbus_Registers''' does the opposite.

=4 HMI IDEs and .CSV Files=
Each line in the .csv file generated by the MCMBConfigurator file holds data about a single variable, such as Modbus address or data type.

This data can be used by an HMI IDE to import Modbus tags and associate them with HMI functionality.

Different manufacturer IDEs use different .csv formatting; therefore, various Python scripts are used to create the specific .csv files suitable for a particular manufacturer IDE.

==JMobile Studio==
Python script: '''JMobile_csv.py'''

Default target .csv file name: '''JMobile_HMI.csv''' (user-definable)

To import tags, perform the following procedure in JMobile Studio.

===Define Protocol===
1. In the ProjectView pane, select '''Protocols'''.

2. Click the blue '''+''' sign.

3. From the list, select Modbus TCP.

4. In the Modbus TCP configuration window, define:

:IP Address: Set the IP address of your softMC.

:PLC Models: Select '''Generic Modbus''' (0-based), meaning the softMC Modbus server starts addressing tags from 0.

:Click '''OK'''.

[[File:softMC_Modbus_HMI_(7).png|600px]]
 
 
===Import Tags===
1. In the ProjectView pane, select '''Tags'''.

2. From the list, select '''Modbus TCP''' protocol defined previously.

[[File:softMC_Modbus_HMI_(8).png|600px]]
 
 
3. Click the '''Import Tags''' button.

4. Open the generated file '''JMobile_HMI.csv'''.

[[File:softMC_Modbus_HMI_(9).png|600px]]
 
 
5. Select the tags you want to add to your project, and click the ''Import tags'' button.

[[File:softMC_Modbus_HMI_(10).png|600px]]
 
 

==AdvancedHMI==
AdvancedHMI is an open source project (http://www.advancedhmi.com/), which is downloaded as a Visual Basic project. You can then open the project, add widgets, compile, and run it.

[[File:softMC_Modbus_HMI_(11).png|600px]]
 
 
1. Drag and drop '''ModbusTCPCom''' into MainForm.vb [Design].

2. The driver appears the bottom of the screen (circled in green).

:Click the driver, and then use the Properties pane (circled in red) to setup the IP address of the Modbus server.

:For example, drag and drop DigitalPanelMeter and MomentaryButton into MainForm.vb [Design].

[[File:softMC_Modbus_HMI_(12).png|600px]]
 
 
3. For both widgets, use the Properties pane to set the Modbus address that is associated with the variables from the softMC application.

[[File:softMC_Modbus_HMI_(13).png|600px]]
 
 
'''Note''':
::MC Modbus server addressing starts from '''40000'''.
::AdvancedHMI Modbus client addressing starts from '''40001'''.
::Prefix the address with the letter '''L'''.

4. Save the project (Ctrl+S).

5. Build the project (Ctrl+Shift+B).

6. Run the project (F5).

Modbus Communication API

2016-04-17T07:39:12Z

Omri: changed appereance

Modbus Communication API

2016-04-17T07:38:23Z

Omri: Added valid input parameters and error codes

Modbus Communication API

2016-04-17T07:14:10Z

Omri: Added valid input parameters and error codes

Modbus Communication API

2016-04-12T14:52:39Z

Omri: added error codes

Modbus Communication API

2016-04-12T14:40:07Z

Omri: /* Initializing a Modbus Server */ added error codes

Modbus Communication API

2016-04-12T14:33:39Z

Omri: Modbus new API: Draft 4

Modbus Communication API

2016-04-12T14:00:21Z

Omri: Modbus new API: Draft 3

== Overview ==
=== Basic Overview ===
This describes how to set up Modbus communication for the softMC, and how to generate softMC scripts to handle Modbus communication.
It is assumed you are familiar with the principles of Modbus communication, although some of them will be described in this page.
It is also assumed your are familiar with the softMC, ControlStudio and MC-Basic programming.

=== Modbus Communication Background ===
* A Motion Controller (MC) can act as a server (slave), a client (master) or both at the same time.
* Each MC connection (TCP/RTU) can be used either as a server component (if the connection is used by the MC’s server-side) or as a client component (if the connection is used by the MC’s client-side).
* Each component has its own parameters that defines it.
* When the MC acts as a server, all server components share the '''same''' memory address space, thus acting as 1 server with multiple connections.
* Each server (slave) on a Modbus network has its own deviceID, which is a number between 1 and 247.

=== The Modbus server registers ===
* The types of registers in the Modbus Server address space include the following:
*# Bits (1-bit registers)
*# Input Bits (1-bit READ-ONLY registers)
*# Holding Registers (16-bit registers)
*# Input Registers (16-bit READ-ONLY registers)
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.

== Getting Started ==
In order to get started in using the Modbus features:
# Using the ControlStudio File Manager, Upload the following files to your MC:
## mb_x86.O ''(for X86 Systems)'' / mb_armA9.O ''(for ARM Systems)''
## Modbus.lib
#* '''Notice:''' From now on, in our examples, we'll use the X86 configuration. [[File:modbus;newAPI-upload.jpg|850px]]
# Load the files to memory, by typing (in the Terminal):
#:<pre>
#::Oload mb_x86.O
#::loadglobal Modbus.lib</pre>

== Initializing a Modbus Server ==
* To initialize the Modbus server address space, call:
*:<pre>
*::?init_multi_server([bits],[input_bits],[holding registers],[input_registers])</pre>
* The function prints "success" and returns 0 on success, or return an error code on failure.
* '''Notice:'''
** This is '''NOT''' required when softMC does not run a modbus server.
** You can call this method only if no servers are running.

== Server Components ==
=== Adding server components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Creating a TCP server component ====
<pre>handle = mb_tcp_server_create([port],[deviceID])</pre>
* This opens a TCP connection to the server on port [port] with deviceID [deviceID], and starts the created server immediately.
* Returns a handle on success, or an error code on failure.
==== Creating an RTU server component ====
<pre>handle = mb_rtu_server_create([type],[port],[baudrate],[data bits],[stop bits],[parity],[deviceID])</pre>
* This opens an RTU connection with the given parameters, and starts the created server immediately.
* Returns a handle on success, or an error code on failure.

=== Stopping Server Components ===
==== Stopping a specific server component ====
You can stop a specific server component by passing its handle to:
<pre>result = mb_server_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate server component.
* Returns 0 on success, -1 on failure.
==== Stopping all server components ====
You can stop all server components with a single call to:
<pre>result = mb_server_stop_all</pre>
This function will:
* Stop and free all server components.
* Free the shared address space.
* Return 0 on success, -1 on failure.

== Client Components ==
=== Adding client components ===
* Each time you'll add a component, you will receive a '''handle''', which is the component's identifier (for later use).
* It is best to keep this handles in variables inside your program.
==== Adding a TCP Client component ====
<pre>handle = mb_tcp_client_create([ip],[port])</pre>
* This will opens a TCP connection to the client on the given ip and port, and start the client immediately.
* Returns a handle on success, -1 on failure.
==== Adding an RTU Client component ====
<pre>handle = mb_rtu_client_create([type],[port],[baudrate],[data bits],[stop bits],[parity])</pre>
* This will open an RTU connection to the client with the given parameters, and start the client immediately.
* Returns a handle on success, -1 on failure.
=== Stopping client components ===
A specific client can be stopped by calling:
<pre>result = mb_client_stop([handle])</pre>
* Given a handle, this will stop and free the memory of the appropriate client component.
* Returns 0 on success, -1 on failure.

== Reset the Modbus System ==
Sometimes, a user may wish to stop all server and client components at once, and reset the Modbus system (for example, when a user want to initialize a different Modbus system). To do that, call:
<pre>result = mb_reset</pre>
This function:
* Stops all running servers and clients.
* Frees their memory.
* Frees the shared address space.
* Reset the handle counter.
* Returns 0 on success, -1 on failure.

== Reading and Writing ==
* Servers can read and write their own address space.
* Clients can read and write a remote server’s address space.
* Therefore, Servers and clients use different functions to read/write data from the address space.
=== Server Components ===
==== Reading ====
===== Reading from Holding registers =====
<pre>
Val = MB_SERVER_READ_REG_LONG(…)
Val = MB_SERVER_READ_REG_SHORT(…)
Val = MB_SERVER_READ_REG_FLOAT(…)
Val = MB_SERVER_READ_REG_DOUBLE(…)
</pre>
===== Reading from Bits registers =====
<pre>val = MB_SERVER_READ_BIT([addr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_SERVER_READ_INREG_LONG(…)
Val = MB_SERVER_READ_INREG_SHORT(…)
Val = MB_SERVER_READ_INREG_FLOAT(…)
Val = MB_SERVER_READ_INREG_DOUBLE(…)
</pre>
===== Reading from Input Bits registers =====
<pre> val = MB_SERVER_READ_INBIT([addr])</pre>
==== Writing ====
===== Writing to holding registers =====
<pre>
Val = MB_SERVER_WRITE_REG_LONG(…)
Val = MB_SERVER_WRITE_REG_SHORT(…)
Val = MB_SERVER_WRITE_REG_FLOAT(…)
Val = MB_SERVER_WRITE_REG_DOUBLE(…)
</pre>
===== Writing to Bits registers =====
<pre>val = MB_SERVER_WRITE_BIT([addr],[value])</pre>
===== Writing to Input registers =====
<pre>
Val = MB_SERVER_WRITE_INREG_LONG(…)
Val = MB_SERVER_WRITE_INREG_SHORT(…)
Val = MB_SERVER_WRITE_INREG_FLOAT(…)
Val = MB_SERVER_WRITE_INREG_DOUBLE(…)
</pre>
===== Writing to Input Bits registers =====
<pre>val = MB_SERVER_WRITE_INBIT([addr],[value])</pre>

=== Client Components ===
==== Reading ====
===== Reading from Holding registers =====
<pre>
Val = MB_CLIENT_READ_REG_LONG([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_REG_SHORT(…)
Val = MB_CLIENT_READ_REG_FLOAT(…)
Val = MB_CLIENT_READ_REG_DOUBLE(…)
</pre>
===== Reading from Bits registers =====
<pre>val = MB_CLIENT_READ_BITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
===== Reading from Input registers =====
<pre>
Val = MB_CLIENT_READ_INREG_LONG ([handle],[deviceID],[addr],[dest ptr])
Val = MB_CLIENT_READ_INREG_SHORT(…)
Val = MB_CLIENT_READ_INREG_FLOAT(…)
Val = MB_CLIENT_READ_INREG_DOUBLE(…)
</pre>
===== Reading from Input Bits registers =====
<pre>val = MB_CLIENT_READ_INBITS ([handle],[deviceID],[addr],[num of bits],[dest arr ptr])</pre>
==== Writing ====
===== Writing to Holding registers =====
<pre>
Val = MB_CLIENT_WRITE_REG_LONG([addr],[val ptr],[deviceID])
Val = MB_CLIENT_WRITE_REG_SHORT(…)
Val = MB_CLIENT_WRITE_REG_FLOAT(…)
Val = MB_CLIENT_WRITE_REG_DOUBLE(…)
</pre>
===== Writing to Bits registers =====
<pre>val = MB_CLIENT_WRITE_BIT([addr],[val ptr],[deviceID])</pre>
=== Reading and Writing Summary ===
[[File:modbus;newAPI-readwriteSummary.jpg|850px]]

Modbus Communication API

2016-04-12T13:59:41Z

Omri: Modbus new API: Draft 2

Modbus Communication API

2016-04-12T13:49:33Z

Omri: Created page - Draft: 1