The Extended Modbus Library was developed by Ola Bjørnli and published on GitHub. It has since been incorporated into the Siemens Open Library, which is maintained by DMC.
This library extends and simplifies the built-in Modbus functionality within Siemens TIA Portal, giving developers a more flexible and user-friendly way to work with Modbus devices. Ola Bjørnli’s provided examples and documentation, found on GitHub, do a great job breaking down how to use the library.
How the Extended Modbus Library Works With Modbus TCP
Here is an example of how to set up a Modbus TCP client.
Block Interface
To maximize reusability, we have set up our inputs to include:
- Connection ID – Unique identifier for each Modbus Client instance
- Hardware interface – The hardware interface to which the Modbus Server is networked
- TCP port – Typically 502
- IP address – The IP address of the Modbus Sever
This allows the block to be reused for multiple field devices, provided they have the same Modbus interface.
The static data elements are:
- mb_query – This is used to define the Modbus queries; one instance can be reused multiple times
- mb_tcp_ctrl – The function block that establishes connection runs and sequences queries
- mb_delay_between_queries – Spaces out queries to avoid overloading the server
- modbusRegisters – A custom UDT containing the data to be read from and written to the Modbus server.
The only constant we have defined is the clientNumber, which is the station address. This is usually 0 or 255.
The Code
This is taken almost exactly from Ola Bjørnli’s example, but it is broken up so we can walk through each step.
The initial setup is straightforward:
- Call the mb_tcp_ctrl block
- Map in the interface, connection ID, IP address, and TCP defined in inputs
- Set your timeout to whatever is needed for your application
- Point mb_query to mb_query we set in the static memory
- Call mb_delay_between_queries
- Tie in the same mb_query from static memory
- Set the delay needed for your application
After this initial setup, we need to build our queries. First, looking at the read queries, below are reads for all four types of Modbus registers. Again, the Extended Modbus Library makes this very straightforward:
- Call mb_query for each query you want to run; there is no limit
- data_addr corresponds to the register of the address you are trying to read from
- Data_ptr should point to where you want the data to be stored in
- Here we have a custom UDT in the static memory, this can either be an array of data points or to an individual point
- Mb_addr is the station address we defined as a constant earlier
- Mode is used to tell the query what kind of operation we are performing
- These modes are defined as constants within the static memory of the mb_query we are calling
To write to either the output coils or the analog output holding registers, you set up your query calls as shown below. The only difference is that mode is pointed to the “c.write” struct in mb_query instead of “c.read”, and the data_ptr points to the data on your PLC that you want to write to the Modbus device.
With just these three sections, your code can read and write to any register on a Modbus TCP device!
How It Works With Modbus RTU
Using this library, the code to connect to a Modbus RTU device is almost the exact same as a Modbus TCP device. The only difference is:
- Call mb_rtu1200_ctrl or mb_rtu1500_ctrl instead of mb_tcp_ctrl
- Choose the FB that matches your PLC
- hardware_id should be connected to the port your device is connected to
- buad_rate should be set to match your RTU device’s baud rate
- operating mode should be set based on the table shown below taken from the Siemens information system
Tips, Tricks, and Troubleshooting
Fun With Pointers
When passing data to and from mb_query as shown above, the data is passed by a pointer. The function block then finds the start and the length of the data you pass in, meaning the data types passed in do not matter. For example, you don’t need to just have 16-bit integers used to read from input registers.
This is especially useful when:
- Multiple statuses are bitmapped into a single register
- Can automatically splice it into 16 bools
- A 32-bit datapoint is passed out over two registers
- For example, this can be passed into a single real
These can be handled with custom UDTs, like the one shown below. You must ensure proper alignment with the actual register indexes and account for byte-swapping as needed.
Queries Less Than 16-Bit
If reading fewer than 16 bits (for example, discrete inputs or outputs), use mb_query_bits. While the standard mb_query may still work in some instances, this function is the recommended route to read smaller datasets.
Troubleshooting Overview
The extended Modbus Library uses the Siemens communication blocks (TCON, TDISCON, TSEND, TRECEIVE), meaning you can leverage their error codes for troubleshooting.
Within your function block’s instance memory:
- Navigate within your “ctrl” block and open “MB_CLIENT” to view error codes
- You can dig into the individual T-blocks as needed
Troubleshooting Queries
It is important to note that each query is executed independently, and if a query fails from a configuration issue, an invalid register, or anything else, it will be skipped, and the next query will be executed.
The error codes for that query will only be displayed until the next query is run. To debug:
- Comment out all but one query at a time
- Troubleshoot until no errors are present and the data is being populated or sent as expected
Ready to take your automation project to the next level? Contact us today to learn more about our solutions and how we can help you achieve your goals.