Kplex Quickstart

Purpose

Kplex has a lot of options. The main configuration page is now long and off-putting for new users. Getting kplex to do what most people want to do is relatively easy. This document attempts to simplify configuration basics. What follows is the easiest way to get kplex working, although not necessarily the best.

Installation

This is covered on the installation page. If you ultimately want kplex to run automatically on boot, don't set that up just yet: we want to configure kplex first..

Configuration

kplex's behaviour can be defined either in a configuration file or on the invocation command line. Any directives given on the command line will be added to (if compatible) or override (if not) directives given in the configuration file. The default location for the configuration file is /etc/kplex.conf. A kplex.conf is installed with the .deb file, but this file does nothing: it is the equivalent of a blank file: kplex ignores everything on a line after a "#" character. You can replace this file, remove all the lines and add new ones, or simply write your configuration at the end.

The configuration file is used to define kplex's inputs and outputs. Inputs and outputs are referred to as "interfaces". An interface can be an input, an output, or both.

kplex has many global options which can be defined in the configuration file but in this quickstart document we will accept the defaults. We do however need to define some interfaces to make kplex do anything useful. Each interface can be defined by writing its type in square brackets. To declare a serial interface (i.e. a data connection over an attached serial line) you would put:

into the configuration file. Underneath this you then add statements in the format "variable=value" to tell kplex things about the interface such as the device name to use and the baud rate to set it to. Everything you write under an interface declaration in square brackets is considered to be part of the same interface declaration until kplex sees a declaration for another interface in square brackets. As elsewhere, everything after a "#" is ignored. Here's a basic declaration for a serial input interface on /dev/ttyUSB0, running at 38400 baud:

[serial]
# This is a comment and ignored
filename=/dev/ttyUSB0
direction=in
baud=38400

Where possible kplex assumes sensible defaults for values. The standard baud rate for NMEA connections is 4800 so if you don't specify "baud=" this is what kplex will use. kplex assumes your connections are bi-directional unless you tell it otherwise with "direction=in" or "direction=out". It doesn't hurt to explicitly state the default values (e.g. "direction=both"). Some parameters need stating ("filename=" must be stated explicitly for serial interfaces).

kplex has quite a few options for the various interface types though not many obligatory ones. They're all documented on the configuration page.

Serial to Network Conversion

This is what most people want to use kplex for and it's easy to set up. We've already seen how to configure a serial interface for receiving data. To transmit your data over a network your computer needs to have a network interface. This might be an ethernet conection (perhaps connected to a wifi router) or a wireless connection. kplex can interact with networks in many different ways but here we'll only talk about the two methods most commonly used.

kplex works happily with IPv6 (the "next generation" Internet Protocol ("IP")) but here we'll only talk about IPv4 which most users are more familiar with.

Marine applications most commonly want to receive data either by connecting to a TCP Server or by listening for UDP packets. TCP and UDP are methods for data transmission over IP networks, the distinction (which is better described in many places) being that TCP involves a sender and a receiver communicating with each other to ensure that all data are reliably delivered in the correct order, whereas UDP involves a sender transmitting messages which may be received by one or more receivers but which (in the absence of something explicitly added by a programmer) receivers do not acknowledge, so if a message is not seen by one or more of the receivers, the sender is not aware and does not attempt to re-transmit it.

UDP messages ("packets") may be sent to a single receiver, a group of receivers or all devices on a network according to the address used. Marine data applications which use UDP generally use the latter method which is referred to as "UDP broadcast".

Which is the best method? "ça dépend". UDP is much lower overhead. A single packet transmitted may be received by many devices whereas TCP requires data to be transmitted over separate connections for each sender/receiver pair. TCP has overheads in the communication between sender and receiver to ensure that no data are lost or mis-ordered. Often though it doesn't matter if occasional transducer updates are lost. On ethernet networks I prefer UDP for marine data, but for various reasons UDP broadcast over wireless networks can be very unreliable. If practice shows that packet loss is unacceptable with UDP broadcast on your network, use TCP.

You can configure kplex to send data over UDP but also to accept TCP connections (as we shall see).

Modern computers run many processes at once. If a network packet just had an IP address the receiving computer wouldn't know which process to deliver the packet to. A "port" is like a mailbox number in a building. It tells the mail room who the end recipient is. Both TCP and UDP packets contain a "port" number. You can use pretty much any "port" you like so long as sender and receiver agree although ports below 1024 should be avoided as some of these are used by system processes. "10110" is the port reserved with the IANA for NMEA 0183 data. You don't have to use that and some commercial marine serial-to-network devices use other ports, but this is kplex's default unless you specify something else, which generally speaking there should be no need to do.

To configure kplex to transmit data over TCP to anything that requests it, add this to your kplex.conf:

[tcp]
mode=server
direction=out

"mode=server" tells kplex to listen for requests for data from other devices rather than connecting to a remote device. We could tell kplex to listen on a particular network interface but here we haven't so kplex will listen on all its network interfaces. As we haven't told kplex which port to listen on it will listen on the default port, 10110 (we could have appended "port=2000" to make it listen on port 2000 instead). "direction=out" tells kplex only to transmit (not to receive) data. If you omit this kplex will both send and receive data on tcp connections, although most apps you want to connect won't be sending data, only receiving.

One declaration of a TCP server interface for kplex will allow many devices to connect: you don't need a separate declaration for each device you wish to support.

To configure an app to connect to this interface, specify protocol to be TCP, address to be the IP address of the computer running kplex, and port to be 10110.

To configure kplex to send data via UDP broadcast to all devices on a connected network we first need to know the broadcast address to send the data to. kplex can work that out for you if you tell it the name of the network interface you wish to broadcast from. If the network interface is called "wlan0", append this to your kplex.conf:

[udp]
device=wlan0
direction=out

If you want to use a port other than the default 10110 you can specify it by adding "port=" as with the TCP declaration described above. Note that prior to version 1.3.1 the above declaration would not work as desired on some platforms if "wlan0" was also configured for IPv6. In those cases it would be necessary to explicity state the broadcast address to use (e.g. "address=192.168.1.255").

To configure an app to connect to this interface, specify protocol to be UDP and port to be 10110.

Putting it all together, here's a configuration file which takes two serial inputs, one from /dev/ttyUSB0 at 38400 baud and another from /dev/ttyUSB1 at 4800 baud (the default, which is why there's no "baud=4800" statement, although you could put that in if you wanted). Data is transmitted over UDP port 10110 and a TCP server supports TCP connection on port 10110:

[serial]
filename=/dev/ttyUSB0
baud=38400
direction=in
[serial]
filename=/dev/ttyUSB1
direction=in
[tcp]
mode=server
direction=out
[udp]
device=wlan0
direction=out

Further Enhancements

The above is a basic example but there are many other options you can give kplex for more complex functionality. All of these are detailed in the README supplied with the kplex source and on the configuration page

Help and Feedback

If you're stuck, you can post questions to the kplex google group. If this quickstart guide is confusing, it isn't intended to be, so please post suggestions for improvement if you have any!