modbus-cli is a command line utility that lets you read and write data using the Modbus TCP protocol (ethernet only, no serial line). It supports different data formats (bool, int, word, float, dword), allows you to save data to a file and dump it back to your device, acting as a backup tool, or allowing you to move blocks in memory.
Install ruby. Then install the gem:
$ gem install modbus-cli
The pure ruby gem should run on most rubies.
Lets start by reading five words from our device startig from address %MW100.
$ modbus read 192.168.0.1 %MW100 5
%MW100 0 %MW101 0 %MW102 0 %MW103 0 %MW104 0
We chose to write the address in Schneider format, %MW100, but you can also use Modicon naming convention. The following achieves the same as the previous line
$ modbus read 192.168.0.1 400101 5
To read coils run the command
$ modbus read 192.168.0.1 %M100 5
$ modbus read 192.168.0.1 101 5
You get three subcommands, read, write and dump. The dump commands writes data previously read using the read command back to its original location. You can get more info on the commands by using the help parameter
$ modbus read --help
To write data, write the values after the offset
$ modbus write 192.168.0.1 101 1 2 3 4 5
Please be aware that there is no protection here - you could easily mess up a running production system by doing this.
For Schneider format you can choose between different data types by using different addresses, When using Modicon addresses, you may specify the data type with an additional parameter. The supported data types are shown in the following table
|Data type||Data size||Schneider address||Modicon address||Parameter|
|word (default, unsigned)||16 bits||%MW100||400101||--word|
|integer (signed)||16 bits||%MW100||400101||--int|
|floating point||32 bits||%MF100||400101||--float|
|double word||32 bits||%MD100||400101||--dword|
|boolean (coils)||1 bit||%M100||101||N/A|
To read a floating point value, issue the following command
$ modbus read %MF100 2
which should give you something like
%MF100 0.0 %MF102 0.0
$ modbus read --float 400101 2
400101 0.0 400103 0.0
The modbus command supports the addressing areas 1..99999 for coils and 400001..499999 for the rest using Modicon addresses. Using Schneider addresses the %M addresses are in a separate memory from %MW values, but %MW, %MD, %MF all reside in a shared memory, so %MW0 and %MW1 share the memory with %MF0.
Reading and dumping to files
The following functionality has a few potential uses:
- Storing a backup of PLC memory containing setpoints and such in event og hardware failure
- Moving a block from one location in the PLC to another location
- Copy data from one machine to another
First, start by reading data from your device to be stored in a file
$ modbus read --output mybackup.yml 192.168.0.1 400001 1000
on Linux you may want to look at the text file by doing
$ less mybackup.yml
on Windows try loading the file in Wordpad.
To restore the memory at a later time, run the command (again a word of warning, this can mess up a running production system)
$ modbus dump mybackup.yml
The modbus command supports multiple files, so feel free to write
$ modbus dump *.yml
To write the data back to a different device, use the --host parameter
$ modbus dump --host 192.168.0.2 mybackup.yml
or for a different memory location
$ modbus dump --offset 401001 192.168.0.2 mybackup.yml
or for a different slave id
$ modbus dump --slave 88 192.168.0.2 mybackup.yml
Slave ids are not commonly necessary when working with Modbus TCP.
Contributing to modbus-cli
Feel free to fork the project on GitHub and send fork requests. Please try to have each feature separated in commits.
(The MIT License) Copyright (C) 2011 Tallak Tveide Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.