npreal2: Moxa Linux Real TTY Driver
===================================
Email: support@moxa.com.tw
Background
----------
Using this driver, you can use NPort serial ports as local tty ports.
This driver works with Linux kernel 3.x, 4.x, 5.x and 6.x. Before using
this software, make sure the IP configuration of the NPort is correct and
you can access (ping, telnet, ...) it successfully. For the Real COM Mode
and the Redundant COM Mode, you need to set the operation mode of your
NPort correspondingly; the latter mode is only available with certain
series of products.
Preparation
-----------
npreal2 has the following dependencies:
- kernel 3.0 or above and the kernel headers
- gcc, binutils, make, coreutils, awk
- openssl (optional, for Secure Real COM Mode only)
With them available, run the following command to build npreal2 (to enable
the Secure Real COM Mode, append the argument `SSL=1' to `make'; to enable
background polling, append the argument `POLLING=1'):
$ make
Then run the following command as root to install npreal2:
# make install
After installation, run the following command as root (if it has not been done
before) to create the low-privilege user for running `npreal2d' and `redund':
# useradd -r npreal2
Then build the npreal2 kernel module (this needs to be done again after every
kernel upgrade; to enable concurrent open in the Secure Real COM Mode, append
the argument `CONCURRENT=1' to `mxmkdrv'):
# mxmkdrv
Configuration
-------------
Use `mxaddsvr' as root to map NPort serial ports to the host tty ports:
# mxaddsvr server_ip num_port [data_port] [cmd port] [interface]
For redundant mode, use the `-r' option:
# mxaddsvr -r server_ip backup_ip num_port [data_port] [cmd port] [interface]
To unmap an NPort server, use `mxdelsvr' as root:
# mxdelsvr server_ip
The mapping configuration can be seen in `/etc/npreal2d.cf'.
For example, the following command
# mxaddsvr 192.168.3.4 16 4001 966
will add 16 tty ports, all with IP address `192.168.3.4', with data ports
4001, 4002, ..., 4016 and command ports 966, 967, ..., 981, respectively.
The following command
# mxdelsvr 192.168.3.4
will remove all tty ports associated with `192.168.3.4'.
Port mapping
------------
After the serial ports have been mapped, run the following command as root to
load the npreal2 kernel module and set up the tty devices `/dev/ttyr*':
# mxloadsvr
After this, start the npreal2 daemon(s) to actually map the ports (`npreal2d'
for the Real COM Mode, `redund' for the Redundant COM Mode; to prevent the
daemons from double forking and let them log to stderr, append the `-f' option;
for better security, the daemons can also be run as the `npreal2' user):
# npreal2d -t 1
# redund -t 1
NOTE: If you have modified the port mapping with `mxaddsvr' and `mxdelsvr',
for the changes to take effect immediately, you need to stop the npreal2
daemon(s), run `mxloadsvr' again to reset the `/dev/ttyr*' devices, and
then restart the daemon(s).
Misc notes
----------
Huge efforts have been made to clean up the codebase while keeping the interface
nearly intact, by only eliminating obviously unnecessary code. Nevertheless,
the codebase is still extremely crufty and ugly, and cannot be considered
trustable. Even though the crappy user space daemons can be run without root
privilege, the source code of the kernel module is just a little less crappy.
Access to `/dev/ttyr*' is controlled with the `dialout' group: only root and
users in the `dialout' group can read/write these devices. The callout devices
`/dev/ttycur*' have been obsoleted in Linux 2.6. `/dev/ttyr0' to `/dev/ttyr9'
and some tty names represented by decimal numbers are created for compatibility
reasons. Only use `/dev/ttyr*' configured in `/etc/npreal2d.cf'.
To enable or disable Secure Real COM Mode for certain NPort servers, set the
6th field ("ssl") of the corresponding lines in `/etc/npreal2d.cf' to 1 or 0,
respectively. (And you should first pass `SSL=1' to `make'.)
If you don't want your program to be blocked when opening tty ports with NPort
not yet existing, you should pass `POLLING=1' to `make'. This feature will
poll NPort in the background to eliminate the time your program is blocked.
Since openssl causes internal system call error when opening multiple tty ports
concurrently, the opening might be failed. If your application needs to open
tty ports concurrently, you should pass `CONCURRENT=1' to `mxmkdrv'.
NPort driver needs up to one minute to synchronize with the NPort after the
network is down and up again. Therefore, if connection loss occurs again
during this period, data loss might occur.
The default IP address for NPort is 192.168.127.254. For NPort Wireless series,
the default IP address of the Ethernet interface is 192.168.126.254, and the
default IP address of the Wireless LAN interface is 192.168.127.254.