Warning

The program is still under development, it is not yet suitable for its task.

Modshell

Command-driven scriptable Modbus utility

Copyright (C) 2023-2025 Pozsár Zsolt pozsarzs@gmail.com

ModShell is a utility built around a command interpreter, which with the connected peripherals communicates via various ports using the Modbus, DCON and HART protocols.

I. Features

features
version	v0.1
licence	EUPL v1.2
language	en, hu
architecture	amd64, armhf, i386, x86_64
operation system	DOS, FreeBSD, Linux, Windows
user interface	ModShell: CLI and TUI
	XModShell: GUI
running modes	normal or interpreter
variables	max. 128 variables or constants (stored as string)
arrays	max. 32 dynamic size array of variables or constants (elements stored as string)
built-in commands	129 commands in 10 categories with macro and script options)
macros	max. 32
script size	max. 1024 line
example scripts	10 scripts (shellscript and batch file versions)
load from file	registers, script, settings
save to file	command history, console and Modbus traffic, registers, communication settings, user log
auto save to file	general settings and console traffic
export to file	history (TXT), registers (CSV, INI, XML)
import to file	registers (INI, XML)
configurable devices	max. 8 settings, serial and ethernet port
configurable protocols	max. 8 settings, ASCII, RTU or TCP
configurable connections	max. 8 settings by combining the previous two
raw serial communication	read/write serial port and mini serial console with A/N or Hex echo
raw TCP communication	read/write network device and mini TCP console with A/N or Hex echo
raw UDP communication	read/write network device and mini TCP console with A/N or Hex echo
DCON communication	read and write remote devices
HART communication	read and write remote devices
Modbus communication	read and write remote device and copy between devices
	internal server for remote access to own registers
	gateway to access devices using other ports or protocols
	internal serial monitor for decode ASCII or RTU telegrams
direct I/O port access	supported, on Windows with external freeware DLL
local Modbus registers	2x9999 boolean and 2x9999 word type
script syntax plugins	for editors using GtkSourceView, MCEdit, Micro, Nano, Notepad++, NeoVim and Vim
utility scripts	2 script
other utility programs	command line serial Modbus traffic monitor, serial, TCP and UDP echo servers

II. Releases

Planned next releases

...that either will or won't.

v0.1

This is first unstable release.
Unstable, but it is already complete in its intended functionality. The software will not include any new features compared to the previous release, only bug fixes. All types of binary and installation packages will be released along with the source package.

v0.1-beta3

Third user test release.
The software will not include any new features compared to the previous release, only bug fixes. Only a source package will be released.

Actual release

0.1-beta2 Second user test release will be with the following changes:

• new command input;
• new command swp;
• new command stack;
• compressed HTML (CHM) help in addition to the existing online Wiki (only XModShell);
• HART protocol support;
• Modbus/TCP communication;
• TCP/UDP communication on DOS;
• graphical monitoring the change of values over time (only XModShell);
• implementation of additional Modbus functions.
  Only a source package will be released.

Previous releases

v0.1-beta1

First user test release with the following changes:

• Elimination of confusion between the terms 'register number' and 'data address'
• in interpreter mode, passing parameters from the OS command line to the script and returning the script's exit value to the OS
• in interpreter mode, command verbosity level setting with a predefined variable
• ANSI escape sequences support (only DOS and *nix like systems)
• command `color` -> `set color`, sets all default colors (CLI and TUI)
• command `echo` -> `echometh`, parameters: off/on/hex/swap -> off/an/hex/swap
• commands `sercons`, `tcpcons`, `udpcons`: character-to-character or string sending, with alphanumerical or hexadecimal input, with or without alphanumerical or hexhexadecimal echo
• commands `serwrite`, `tcpwrite`, `udpwrite`: alphanumerical or hexadecimal input, with or without alphanumerical or hexadecimal echo
• DCON protocol support
• keywords (coil, hreg, asc, hex, etc.) should also be specified from variables
• main menu for all consoles in GUI version
• Modbus register number/address converter utility (in your own scripting language)
• Number converter utility (in your own scripting language)
• modified source code structure of XModshell
• new command `chkdevlock`/`rmdevlock` (only *nix systems)
• new command `datatype`
• new command `exist`
• new command `inputmeth`
• new command `macro`
• new command `mbconv`
• new command `mbmon`
• new command `printcolor`(only CLI and TUI)
• new command `runmeth`
• new command `sendmeth`
• new command `tcpcons`, `tcpread`, `tcpwrite`
• new command `udpcons`, `udpread`, `udpwrite`
• new commands `ioread` and `iowrite`
• new menu items in the main menu for quick execution of Modbus R/W commands
• new menu items for show and edit all register's value in a big table
• new serial baudrates: 150, 300, 600 baud
• serial echo server utility for testing connectivity
• serial ModBus traffic monitor utility
• support for variable and constant arrays
• new predefined constants
• syntax highlighter file for applications using GTKSourceView (for example: Builder, Geany, Gedit, Mousepad, Pluma, Scribes), for Notepad++ (Windows only) and Vim/Neovim
• TCP and UPD echo server utilities for testing connectivity.

Only a source package will be released.

v0.1-alpha3

Third and last developer test release with the following changes:

• New source code directory structure;
• new commands;
• new predefined constants;
• bug fixes;
• GUI (except DOS);
• script syntax highlighting file for MCEdit and Nano.

Only a source package will be released.

v0.1-alpha2

Second developer test release with the following changes:

• Bug fixes;
• Modbus/ASCII and Modbus/RTU communication;
• handling of constants;
• three predefined constants and
• 28 new command (total: 94);
• script syntax highlighting file for Micro.

All types of binary and installation packages will be released along with the source package.

v0.1-alpha1

First developer test release is not yet suitable for work, although it is functional, but it can only communicate via Modbus/ASCII. The purpose of this release is to test the program's construction, operation, packaging, and package installation in all supported environments. In addition, the documentation and other files are checked for possible typos and errors. Only a source package will be released.

III. Screenshots

ModShell

Normal command line

Fullscreen command line

Run example script on bash with ModShell interpreter

XModShell

Dump input registers

Input registers in Register table

Mini serial console

Script editor

Variable monitor

IV. Used external libraries

• Convert - Bin/Oct/Dec/Hex number converter
  Unit for Turbo Pascal v3.0
  Public Domain, Copyright (C) 1993 Tom Wellige
• Ararat Synapse Release 40 ¹
  TCP/IP and serial library for FreePascal
  Modified BSD style license, Copyright (C) 1999-2012 Lukas Gebauer
• ProtCOM v0.1 Protected mode serial port handler for DOS ²
  Unit for FreePascal
  Creative Common Zero Universal v1.0, Copyright (C) 2024 Pozsar Zsolt
• InpOut32 v1.0.07 Driver Interface DLL ³
  Windows Dynamic Link Library (DLL)
  Open source/freeware Copyright (C) 2003-2015 Phil Gibbons Copyright (C) 2000 <logix4u.net>

V. About the program in a nutshell

This is a utility that can be used on several operating systems, which can communicate with connected equipment using Modbus/ASCII, Modbus/RTU and Modbus/TCP protocols ⁴. The basic communication protocol of the program is Modbus, but DCON and HART was also implemented due to communication with other devices. The range of foreign protocols may be expanded later. The program can - even automatically - read, write or copy data from one device to another (e.g. transferring settings). When copying, the source and destination register areas can be different.

The ModShell program has a traditional (CLI) or full-screen (TUI) command-line interface and is also suitable for running pre-created scripts independently (as a command interpreter). The program provides help on the commands that can be used, and offers possible values when the parameters are entered incorrectly. The issued commands are placed in history, which can be browsed with the up/down arrow keys.

The XModShell program has a graphical interface (GUI), which helps to perform several operations with dialog windows, but the original command line input remained available for them (e.g. file selection, settings, etc.) ⁵.

Operating principle

It must be defined the I/O devices, then the protocols and the connections. There can be eight of each. The data traffic takes place between the preset connections. In all cases, the data is sent to or read from the internal buffer. The size of the buffer is suitable for storing 2*9999 logical and word values of the same size.

128 variables and 32 arrays (which can also be constants) can be created in the program, to which we can assign a value of any type (eg.: string, boolean or integer register value, real number, etc.). Variables and constants can be used to perform logical and arithmetical operations, and can be used to pass values to commands.

It is possible to create 32 single-line macros to replace frequently used longer commands. The program includes 3 pre-created macros, the content of which can also be changed.

Projects

In the program, you can create projects for easier management of settings and data. The name of the current project is shown in the prompt. The project directory will be created in the program directory on DOS, and in the ModShell directory in the user's home directory on all other systems. If only filename is specified during file operations (without path), this directory will be the source/destination directory.

File operations

The command line history can be exported to a text file and provides it with the appropriate 'shebang' for the installation method and operating system. You can easily create a script from this raw file.

Device, protocol and connection settings can be saved and loaded in their own format. During saving, three typed files are created, with the following extensions: DDT, PDT, CDT.

All register values can be saved and loaded in their own format. During saving, two typed files are created, with the following extensions: BDT, IDT.

One or more same type registers can be exported to file. During saving, one text file is created, with CSV, INI or XML extension. The program can only import from INI and XML format files.

We can also create time-stamped log entries with the program and or script.

On exit, the command line history, input and echo mode and colors are preserved.

The program also has basic file and directory management commands.

Script operations

The script on the disc can be loaded into the already running program and started manually.

The loaded script can be edited with a line editor, saved to disk or deleted from the buffer. The graphical version has a simple editor window with syntax highlighting instead of the line editor.

Variables, constants and macros defined before running the script will be deleted. It is also possible to observe the values of up to four variables during runtime and to keep the final values​of constants and variables created during runtime.

In interpreter mode, operating system command line arguments are available as predefined constants.

Raw serial connection

The program provides the possibility to send and receive raw data via a serial port, and also includes a very simple serial console. The display of sent and received data can be turned off or raw text and hexadecimal viewing can be selected.

Serial connection with DCON protocol

The program also provides the possibility to send and receive data with DCON protocol via a serial port.

Serial connection with HART protocol

The program also provides the possibility to send and receive data with HART protocol via a serial port. A serial/HART gateway may be required for connection.

Raw TCP connection

The program provides the possibility to send and receive raw data via network device with TCP, and also includes a very simple TCP console. The display of sent and received data can be turned off or raw text and hexadecimal viewing can be selected.

Raw UDP connection

The program provides the possibility to send and receive raw data via network device with UDP, and also includes a very simple UDP console. The display of sent and received data can be turned off or raw text and hexadecimal viewing can be selected.

Direct I/O access

The program provides direct, byte-sized reading and writing of hardware I/O ports. On Windows operating systems, it uses the included external dynamically linked library.

VI. Implemented commands

	command	category	hotkey	description
1	add	arithmetic		addition
2	avg	arithmetic		average calculation
3	conv	arithmetic	ALT-C	convert numbers between BIN, DEC, HEX and OCT format
4	cos	arithmetic		cosine function
5	cotan	arithmetic		cotangent function
6	dec	arithmetic		decrement integer
7	div	arithmetic		division
8	exp	arithmetic		natural exponential
9	idiv	arithmetic		integer division
10	imod	arithmetic		modulus division
11	inc	arithmetic		increment integer
12	inrange	arithmetic		check the value is in the range
13	ln	arithmetic		natural logarithm
14	mul	arithmetic		multiplication
15	mulinv	arithmetic		multiplicative inverse
16	odd	arithmetic		odd or event
17	pow2	arithmetic		exponentiation of two
18	pow	arithmetic		exponentiation
19	prop	arithmetic		propotional value calculation (with zero and span)
20	rnd	arithmetic		create random integer
21	round	arithmetic		round real number
22	sin	arithmetic		sine function
23	sqr	arithmetic		square
24	sqrt	arithmetic		square root
25	sub	arithmetic		substraction
26	tan	arithmetic		tangent function
27	copyreg	communication		copy one or more remote registers between two connections
28	dcon	communication		read or write data from/to remote device with DCON protocol
29	hart	communication		read or write data from/to remote device with HART protocol
30	mbconv	communication		Modbus register number/address converter
31	mbgw	communication		start internal Modbus gateway
32	mbsrv	communication		start internal Modbus slave/server
33	mbmon	communication		start serial Modbus traffic monitor
34	readreg	communication	ALT-R	read one or more remote registers
35	sercons	communication	F7	mini serial console
36	serread	communication		read string from a serial device
37	serwrite	communication		write string to a serial device
38	tcpcons	communication	SHIFT-F7	mini TCP console
39	tcpread	communication		read string over the network using TCP
40	tcpwrite	communication		write string over the network using TCP
41	udpcons	communication		mini UDP console
42	udpread	communication		read string over the network using UDP
43	udpwrite	communication		write string over the network using UDP
44	writereg	communication	ALT-W	write data to one or more remote registers
45	get	configuration	ALT-G	get device, protocol, connection, colors, project name and timeout
46	reset	configuration	ALT-T	reset device, protocol or connection or reset project name
47	set	configuration	ALT-S	set device, protocol, connection, colors, project name and timeout
48	applog	file		append a record to log file (LOG)
49	exphis	file		export command line history to file (TXT)
50	expreg	file	ALT-E	export one or more registers to file (CSV, INI, XML)
51	impreg	file	ALT-I	import one or more registers from file (INI, XML)
52	loadcfg	file	F3	load settings of device, protocol and connection (?DT)
53	loadreg	file	F5	load all buffer registers from typed file (?DT)
54	savecfg	file	F2	save settings of device, protocol and connection (?DT)
55	savereg	file	F4	save all registers to typed file (?DT)
56	arrclear	general		clear content of an array
57	arrfill	general		fill an array with a character
58	ascii	general		show ASCII table
59	beep	general		make a beep with internal speaker
60	carr	general		show all constant arrays with theirs size or define a new one
61	cls	general	F8	clear screen
62	const	general		show all constants with theirs value or define a new one
63	cron	general		loaded script scheduled execution
64	datatype	general		detect type of data
65	date	general		show system date and time
66	echometh	general	F9	alphanumerical/hexadecimal/none local echo method for connections
67	exit	general	F10	exit
68	for	general		loop iteration
69	getarrsize	general		get size of an array
70	goto	general		jump to specified label
71	help	general	F1	show description or usage of the commands
72	if	general		selection statement
73	input	general		input data from console
74	inputmeth	general	SHIFT-F9	alphanumerical/hexadecimal data input method for connections
75	label	general		define label (for goto command)
76	let	general	ALT-L	set value of a register, variable, a constant or an element of array
77	macro	general		show all macros with theirs value or define a new one
78	pause	general		waits for a keystroke or specified time
79	printcolor	general		set temporary foreground and background colors for print in CLI/TUI
80	print	general	ALT-P	print message, value of the variable and register
81	runmeth	general		get execution method
82	sendmeth	general	CTRL-F9	char-to-char or string data send method for connections
83	setarrsize	general		set size of an array
84	var	general		show all variables with theirs value or define a new one
85	varmon	general	ALT-M	monitoring the value of variables
86	varr	general		show all variable arrays with theirs size or define a new one
87	ver	general		show version and build information of this program
88	and	logic		AND logical operations
89	bit	logic		value of the specified bit
90	not	logic		NOT logical operations
91	or	logic		OR logical operations
92	roll	logic		roll bit of integer to left
93	rolr	logic		roll bit of integer to right
94	shl	logic		bit shift to left
95	shr	logic		bit shift to right
96	xor	logic		XOR logical operations
97	dump	register	F6	dump all registers in binary/hexadecimal format to a table
98	edit	script	SHIFT-F4	edit loaded script with line editor
99	erasescr	script	SHIFT-F8	erase script from buffer
100	list	script	F11	list loaded script
101	loadscr	script	SHIFT-F3	load ModShell scriptfile from disc
102	run	script	F12	run loaded script
103	savescr	script	SHIFT-F2	save loaded script to disc
104	chr	string		convert byte to char
105	concat	string		concatenate strings
106	length	string		length of string
107	lowcase	string		conversion to lowercase
108	mkcrc	string		make CRC value
109	mklrc	string		make LRC value
110	ord	string		convert char to byte
111	strdel	string		delete specified element(s) of the string
112	strfind	string		find specified element in the string
113	strins	string		insert element into string
114	stritem	string		specified element of the string
115	strrepl	string		replace element in the string
116	upcase	string		conversion to uppercase
117	cd	system		change actual directory
118	chkdevlock	system		check device lock file
119	copy	system		copy file
120	del	system		remove file
121	dir	system		list directory content
122	exist	system		existence of a file or directory
123	ioread	system		read a byte from an I/O port
124	iowrite	system		write a byte to an I/O port
125	md	system		make directory
126	rd	system		remove directory
127	ren	system		rename file
128	rmdevlock	system		remove device lock file
129	type	system		type file

(Commands with function keys (F?) are executed immediately, modifier keys (ALT-?) only make typing easier.)

VII. Predefined things

Predefined variables

name	value
$verbose	verbosity level (values: NOTHING

Empty and any other variable value are equivalent to ALL.

Predefined constants

name	value
$?	exit value of the commands
$ARGx	OS command line arguments (interpreter mode)
$ARGCNT	number of the OS command line arguments (interpreter mode)
$B01	150 (baud)
$B03	300 (baud)
$B06	600 (baud)
$B1	1200 (baud)
$B2	2400 (baud)
$B4	4800 (baud)
$B9	9600 (baud)
$B19	19200 (baud)
$B38	38400 (baud)
$B57	57600 (baud)
$B115	115200 (baud)
$EULER	value of e (2.7182818284590452354)
$HOME	user's home directory
$PI	value of Pi (3.1415926535897932385)
$PRJDIR	directory of the actual project
$PRJNAME	name of the actual project
$SQRT2	value of square root of 2
$SQRT3	value of square root of 3

Predefined macros

name	value
mydev0	set dev0 set /dev/ttyUSB0 9600 8 n 1
mypro0	set pro0 rtu 1
mycon0	set con0 dev0 pro0

These macros can also be changed.

VIII. Documentation and Help

Modshell and XModShell has a minimal built-in help which you can access by typing help. Additionally, you can view the manual page from *nix shell (man modshell) or modshell.txt on other systems.

In the graphical version, the Online Wiki can be opened directly from the 'Help' menu.

IX. Contributing

If you find any bugs, please report them! I am also happy to accept pull requests from anyone. You can use the GitHub issue tracker to report bugs, ask questions, or suggest new features.

X. Links

• Homepage
• GitHub repository
• Project webpage on Github
• Online manual on Github

Source packages

name	version
main.zip	latest
modshell-0.1beta1.tar.gz	v0.1-beta1
modshell-0.1alpha3.tar.gz	v0.1-alpha3
modshell-0.1alpha2.tar.gz	v0.1-alpha2
modshell-0.1alpha1.tar.gz	v0.1-alpha1

Binaries and installer packages for several OS and architecture

Not all test versions have binary or installation packages. To download, visit Modshell's webpage.

Footnotes

1. Synapse Github repository ↩

2. ProtCOM Github repository ↩

3. InpOut32 Github repository ↩

4. Modbus ↩

5. Wiki - Differents between CUI and GUI version ↩