Tech!
Kplex Home
Overview
Install
Config
Download
Changelog
Issues
Contact
top border

Kplex 1.5 beta

This release adds some significant new features. There are no significant bug fixes so it should not be necessary for existing users to upgrade if they don't need the new features, although community testing is always appreciated!

Configuration information for the latest beta release can always be found on the beta configuration page.

What's new?

This release adds some significant new features.

Bugs fixed in this release:

  • Minor fix to Makefile
  • Correct behaviour of "coalesce" option
  • Fix erroneous re-reading of data on bi-directional udp broadcast interfaces
  • Drop impossibly short sentences
  • Fix systemd unit file

Beta Caveats

This is pre-production software. It is more likely to have bugs than a full release. Features may change and options may change if ongoing testing suggests alternatives would be better. Please do leave feedback, if you are using this version, even if only "Works for me".

Obtaining and Installing the Beta Release

1.5 is not yet ready for Beta testing so there is no binary release, but those that wish to experiment can check out and compile the "develop" branch on github. Please leave feedback via the kplex google group!

For compiling and installing, just follow the normal kplex installation instructions.

New Features and How to Use Them

Message Internationalization

System error messages will now be displayed in the language of the current locale. kplex messages will be displayed in the language of the current locale if a translation exists (under /usr/share/kplex/locale with most Linux installs ). Translations may not always be complete meaning that untranslated messages will still be in English. Initially the only language other than English supported for kplex messages is Netherlands Dutch. Errors/omissions/further translations gratefully accepted.

Further details including how to help with translation are here: http://www.stripydog.com/kplex/i18n.html.

Application-level keepalives

A new per-interface "heartbeat" option tells kplex to send out an NMEA sentence from the specified interface with a given frequency (in seconds). The sentence looks like: $PKPXI,HB*7C (terminated with "\r\n" or "\n" according to interface type and configuration).

The "heartbeat" option can be applied to any bi-directional or output interface. Its argument is the frequency of the heartbeat in seconds so: heartbeat=300 will send out a heartbeat sentence every 5 minutes.

Possible use case include:

  • Maintaining firewall/NAT state on connections with infrequent data. This can also be achieved using tcp keepalives via the "keepalive" option.
  • Ensuring regular reconnection of dropped connections when using the "persist" option with outbound-only interfaces. kplex only notices dropped "direction=out" connections when attempting to write something, so connections with infrequent data transfer take a long time to reconnect. This is not normally an issue and does not aplpy to bi-directional connections, but the heartbeat option ensures outbound connections regularly have some data to write.
The implementation of heartbeats includes a framework for scheduling and re-scheduling future events which may have other uses.

Expanded checksum option

Currently the "checksum" option has two possible values:

  • "yes", meaning incoming sentences are dropped unless they have a correct checksum
  • "no" (the default), meaning no checksum checking is performed.

In this release the checksum option still defaults to "no" but may take the following additional values:

  • "strict", a synonym for "yes".
  • "loose", meaning checksum checking is performed and sentences with incorrect checksums discarded, but sentences without checksums are accepted.
  • "add", meaning checksum checking is performed and sentences with incorrect sentences are discarded, but those without checksums have one added.
  • "addonly", meaning checksum checking is not performed, but sentences without checksums have one added.

With the "add" and "addonly" options, sentences without checksums which are too large to have a checksum added and remain within the maximum length of an NMEA-0183 sentence are discarded.

Extended filename option for "file" interfaces

A new option has been added to file interfaces to allow substitution of certain values into an input or output filename. The option is:
filenamex=<format>
Where <format> is either "-" to specify stdin or stdout, or a format string where variables preceded by the "%" character are substitued per the strftime(3) library call. Additionally filenamex will substitue certain variables specified as %{<keyword>}. Currently only one <keyword> is recognised: %{host} in a format string is replaced by the hostname of the system on which kplex is running.

As an example, an interface specified as:

[file] direction=out filenamex=/var/log/kplexout.%{host}.%Y-%m-%d

Would, when run on host pluto.example.com on April 1st 2021 produce a log file called "/var/log/kplex.pluto.example.com.2021-04-01".

Note that kplex does not roll log files. This feature was requested by multiple users but for most people use of utilities like "logrotate" to rotate and rename log files may be a better option.

Known Issues with Current Beta Version

  • Some async-unsafe code lurks in the signal handler which terminates threads. It could theoretically cause kplex to crash or hang on exit but this has never been reported.

Beta version history

bottom border