Kplex

kplex: A multiplexer for various nmea 0183 interfaces Copyright Keith Young 2012-2018 stripydog7@gmail.com Blurb: Details of the GPLv3 under which this software is distributed can be found in the file COPYING in this directory.

This software almost certainly contains bugs and should not be relied on as part of a safety critical system, ie as a sole source of marine navigational information.

Installation From Source

You've got this far so you've unpacked it. So "make" should be the obvious next step. If you're using FreeBSD or some other system where GNU make is not default, you make have to type "gmake" instead. There's only one executable ("kplex").

"make install" will install kplex into /usr/bin on Linux systems, /usr/local/bin on other systems. You can change this by setting BINDIR. ie to install to /usr/sw/bin use: make -D BINDIR=/usr/sw/bin install alternatively if using sh/ksh/bash: BINDIR=/usr/sw/bin make install

The "install" target does not install a start script. Tihs must be done manually if required. It does not create a configuration file. The file "kplex.conf.ex" can be used as a starting point to create your own configuration file using the information contained in this README file.

"make uninstall" will remove the kplex binary. If you specified a non-standard installation location using BINDIR, specify it again for the uninstall target.

If you want to have kplex start on boot, kplex.init is an example init script for debian-derived systems. It expects kplex to be installed in /usr/bin and a configuration file in /etc/kplex.conf. Change these as necessary, install by copying kplex.init to /etc/init.d/kplex and run: update-rc.d kplex defaults to create symlinks in the appropriate rc.d directories.

kplex.init will run kplex as root, but this is neither required nor recommended. To automatically run kplex as a different user, change RUN_AS_USER as appropriate. The user kplex runs as does require permissions to read /write serial interfaces as necessary. Typically this will mean being a member of the group which owns serial devices. On debian-based systems like ubuntu this means adding the user to the "dialout" group.

From .deb file

If you've installed from a debian binary package, the startup script and binary are installed for you. The default start script is not configured to run at boot time but can be made to do so using update-rc.d(8). The start script runs kplex as root but this is not recommended. Instead create a user (e.g. "kplex") and change the RUN_AS_USER definition in /etc/init.d/kplex to specify that kplex run as that user. Be sure to add this user to the group which owns the serial ports (normally "dialout" on modern debian-based systems).

The configuration file the .deb installation installs in /etc/kplex.conf actually does nothing (all directives are commented out). Read the instructions in this README file for how to create a confiuration file. A quick start example which bridges between a tcp server and a 38400 baud serial-to-usb connection is commented out in this example file.

Invocation:

kplex [-V] | [-d 1..9] [-f <filename>] [-p <pidfile>] [-o <option>] <interface> <interface> [<interface> ...]

Where The "-d" flag, if specified, will cause kplex to print debugging information, the verbosity of which is controlled by the flag's argument with "1" producing minimal additional debugging information and "9" producing verbose debug information.

<filename> is the path of a configuration file to use where default options and interfaces are defined. If not specified, kplex will look for its configuration in the following locations and use the first file found:

• A location specified in the KPLEXCONF environment variable
• OSX ONLY: ~/Library/Preferences/kplex.ini. This location is for backwards compatibility, will not be supported in the next major release and its use is discouraged.
• OS ONLY: ~/Library/Preferences/kplex.conf
• ~/.kplex.con
• /etc/kplex.conf

Specifying filename as "-" disables looking for the default configuration files.

<pidfile> is the path of a file where kplex will write its pid for the convenience of mechanisms such as init files used to control system processes. If this option is specified and kplex finds that <pidfile> is locked by another process it will print a warning and exit.

<option> is an option specifier for the form: <varable>=<value> These correspond to configuration options which may otherwise be specified in "global" section of the configuration file (discussed in the "Configuration File" secction below). Command line configuration options always override options given in the configuration file.

<interface> is an interface specifier which takes the form: <interface_type>:<option>[,<option> ...] where: <interface_type> is one of: "serial": serial nmea 0183 data "file": file (or standard in/out) "tcp": nmea over TCP "udp": nmea over UDP (unicast/broadcast/multicast) "broadcast": nmea over UDP broadcast (DEPRECATED) "bcast": synonym for "broadcast" (DEPRECATED) "multicast": nmea over UDP multicast (DEPRECATED) "mcast": synonym for "multicast" (DEPRECATED) "pty": serial nmea data over a pseudo terminal "gofree": nmea over TCP announced by Navico's "GoFree" protocol <option> is one or more options of the form <var>=<val>. Some options are not optional. Options applicable to all interface types are: "direction": May normally be one of "in" specifying an input, "out" specifying an output, or "both" specifying a bi-directional interface. Not all directions are applicable to all interface types. The default is "both" if an interface type permits bi-directional commnuication. It is more efficient to specify "in" or "out" if that is all an interface needs to do. "qsize": Size of the interface's output queue. Not used for input only interfaces. Defaults should be fine. This should only need to be increased from default in the case of a bursty high-speed input feeding a slow ouput. "checksum": May be "yes" to enable checksumming of incoming sentences on an interface or "no" to disable it. This option overrides the global checksum option. "strict": May be "yes" to enable strict parsing of incoming sentences on an interface or "no" to disable it. This option overrides the global strict parsing option. "loopback": May be "yes" to enable sentences read from an interface to be written back to it when communication is bi-directional or "no" (the default) to ensure sentences are not looped back to the interface they were read from. This option should be used with extreme caution and generally not at all with broadcast or multicast interfaces. This option has no effect on unidirectional interfaces. "ifilter": Specifies an input filter (see below) "ofilter": Specifies an output filter (see below) "name": Attaches a symbolic name to an interface. This is only required if you intend to use the interface for failover (see below) but can be helpful for debugging. The value associated with "name" can be any string consisting of letters and or numbers which is not used as the "name" for another interface. If no "name" is assigned kplex will autogenerate one starting with an underscore ('_'). For this reason names starting with an underscore should not be manually assigned. Names are NOT case sensitive, so do not call one interface "Serial" and another "serial". "srctag": Specifies that an NMEA-0183v4 TAG block containing a source identifier be prepended to sentences output on the interface if the value is "yes" or "input". The src identification string is the interface name (see the "name" option above) truncated to 15 characters or the string "kplex" if the interface name starts with an underscore as is the case with autogenerated (non-user-specified) names. A TAG block prepended by the "srctag=yes" option looks like: \s:kplex23
If "srctag=no" is specified, no source identifier is prepended. This is the default. If "srctag=input" is specified, the src identification string is the name of the interface on which the sentence arrived truncated to 15 characters or the string "kplex" if no "name" is specified for the input interface. "timestamp": Specifies that an NMEA-0183v4 TAG block containing UNIX time (for example "\c:14231331105C" should be prepended to sentences output on the interface. The timestamp is in seconds if the value is "s" or milliseconds if the value is "ms". Note that NMEA-0183v4 timestamps do not take account of leap seconds. "optional": If "optional=no" is specified or this option is not given, kplex will exit if it cannot initialize the interface. If "optional=yes" is specified, failure of the interface to initialize will only cause kplex to exit if, as a result of it failing, kplex has no inputs or no outputs.

If source identifier and timestamps are both requested for an interface, they are combined into a single TAG block, source identifier first, e.g.: \s:kplex,c:1423133048*5F\

The -V flag instructs kplex to print its version number and exit. It should not be used with any other options.

Interface Types:

Serial Interfaces

This is the traditional way of getting nmea data into your computer. kplex doesn't care whether your device is connected to via a traditional serial port or via a USB t