Table of Contents
Each source is configured in its own section, starting with a section tag in square brackets (e.g. [Bus01], [DW]) and followed by the source specific configuration values. The name given in the tag is used when printing log messages to identify the source responsible for them and will be used as the source name unless overridden by a name option.
Generic configuration options
Common to almost all supported sources are the options name, type, and sourcenum. Of these, type is mandatory.
The type options identifies which of the supported source types are being configured by this block. Blocks without a valid type specified will generate an error. See supported sources for details of valid type options.
The name option controls the reported source name used in the channel information file, which is then available for subsequent processing and data conversion software. If not provided, it defaults to the section tag. The name is arbitrary information and is not used by the logging software itself.
The sourcenum option controls the ID number used to identify messages from this source. There can be only one source active with a given number for a particular configuration.
If no sourcenum option is present, a suitable value will be configured automatically. Numbers can be specified in decimal or, as shown in the example above, as hexadecimal digits prefixed with 0x.
Supported Sources and Devices
Each source is defined in its own section, with the tag, name, and source number specified as described above. The type option is required before the source specific options will be processed, and unknown options are generally ignored.
Each of the sections below will show a small example configuration section, then provide more detailed explanation of all valid configuration options for that source type. In the configuration examples, "#" marks an explanatory comment that should be omitted when creating your own configuration files.
GPS Source Options
type = GPS
The current GPS code is limited to supporting uBlox based GPS devices attached via a serial or USB connection.
port: Serial port name or path. See also device names.initialbaud: Initial baud rate to use. Some uBlox devices start at a slower rate and need to be reconfigured to a more suitable rate for general data transfer, so set the initial power-up/reset baud rate here.baud: General baud rate to use after initial configuration.dumpall: Enable unfiltered output, passing (and recording) additional messages in the output file. Otherwise, only parsed messages are saved, reducing the size of the recorded data files.
MP Source Options
type = MP or type = SL
This source type is for use with devices that directly output msgpack formatted data as described in the Logger technical details page.
port: Serial port name or path. See also device names.baud: General baud rate to use after initial configuration.
Note that the general sourcenum and name parameters are ignored here, as they will be provided directly by the connected device.
The source tag (MP02 in this example) will be used in any log messages generated by the logging software.
I2C Source Options
type = I2C
There are two general parameters that need to be provided in order to record data from I2C connected sensors.
bus: Path to the I2C bus / device. See device names for some generic considerations herefrequency: Number of sensor readings to request per second.
Unlike most other data sources, I2C readings must be requested by the logging software rather than being recorded on arrival. The frequency set here is a single value per bus, so must be supported by all sensors in use.
After defining the bus name and polling frequency, each individual sensor must be configured. In general, each sensor definition will need to provide a sensor type, I2C address and the (base) channel ID.
The sensor type is provided by the configuration option name (which may be present more than once), with the I2C address and base message ID provided in hex, separated by a colon. In the example configuration, an ADS1015 sensor is being configured at address 72 (0x48) and the first value provided by that sensor will be at channel 4. If the base message ID is missing, a default will be substituted. Mixing automatic and manual allocation of base message ID may lead to conflicts and is not recommended.
INA219 Voltage and current monitor (ina219)
The INA219 chip measures the current being supplied to a circuit through a shunt resistor. Each chip provides three measurements, using three sequential channel numbers:
- Channel
n: Bus voltage (supply voltage to the positive side of the shunt resistor) [Volts] - Channel
n+1: Shunt voltage (voltage drop across the shunt resistor) [millivolts] - Channel
n+2: Current flowing to the load (calculated from the voltage drop across the shunt resistor) [Amps]
Multiple chips can be connected to a single I2C bus using different addresses, and the channel numbers can optionally be set in the configuration file.
To read from an INA219 chip, add the following line to the source definition:
Add additional lines for each chip connected to that I2C bus.
As an example, the Waveshare Current/Power monitor hat could be configured as shown:
ADS1015 ADC (ads1015)
The ADS101x series of analog-digital conversion chips measure analog voltage levels and output that information digitally over I2C. These chips are used in several ADC implementations that can be connected to single board computers (such as a Raspberry Pi) or to microcontrollers (including the Arduino family of devices).
The current implementation assumes that the chip used is an ADS1015 device, which provides 4 inputs. These are assigned channel numbers n to n+3, where n is the base channel ID. Adding an ADS1015 chip as a source requires its I2C address, and optionally the base channel number can be provided as described above for INA219 chips.
Additionally, scaling, offset, and limit values can be provided as colon separated values in order. In this case, the base channel ID must also be supplied. Scaling is applied linearly to each channel, multiplying the original value by the scaling factor and then adding the offset. Values that then lie outside any configured limits will be replaced with NaN values.
The default values are a scale of 1.0, offset of 0 and limits of 
.
In the first of these examples, data from the chip at address 0x47 would be multiplied by 3.22 and offset by -17.75. Note that this would be applied to all four channels. The resulting values would be replaced with NaN if the results are below -15 or above +30.
NMEA Source Options
NMEA 0183
type = NMEA
This source type allows messages broadcast in NMEA0183 format to be captured, with some messages interpreted for more convenient use and analysis. The connected device can either be a single serial device that outputs messages in this format, or a serial interface to an NMEA0183 bus.
Currently, the following messages are parsed into their own channels:
| Talker | Message | Description | Channel Number |
|---|---|---|---|
| II | ZDA | Date / Time | 4 |
All other messages are stored in channel 3 for later extraction and analysis.
NMEA 2000
type = N2K
The newer NMEA 2000 format is a binary encoded message format, similar to CAN messages in the automotive sector. Support for this communications format is currently limited to the Actisense NGT-1 interface, which receives encoded messages from an NMEA 2000 bus and rebroadcasts them via serial or USB to a connected computer.
port: Serial port name or path. See also device names.baud: Serial data baud rate - must match configuration on the Actisense device
The sourcenum and name parameters should also be provided to make later analysis more consistent.
Currently, the following messages are parsed into their own channels:
| PGN | Description | Channel Number |
|---|---|---|
| 129025 | Position (Lat/Lon) | 4 (Lat) / 5 (Lon) |
All other messages are stored in channel 3 for later extraction and analysis.
Datawell Source Options
type = DW
This source type allows data to be recorded from a Datawell Waverider via a RX-C reciever connected to the local network.
host- IP address or DNS name for the RF receiver. The port number is fixed at 1180timeout- Consider the connection lost if no data is received after this period (in seconds).raw- Record raw message data from the receiver in addition to parsed data. Recommended.spectrum- Parse spectral information into data file.- This is not recommended, as much of the structure of the spectral data is not preserved in the output file in this format.
- It is recommended to record raw messages and then extract the data for analysis later.
This source generates several channels of data, the full details of which are documented in the source code for dw_channels().
| Description | Channel Number |
|---|---|
| Raw Data | 3 |
| Signal | 4 |
| Displacement N | 5 |
| Displacement W | 6 |
| Displacement V | 7 |
| Latitude | 8 |
| Longitude | 9 |
| Orientation | 10 |
| Inclination | 11 |
| GPS Status | 12 |
| RMS Height | 13 |
| Reference Temperature | 14 |
| Water Temperature | 15 |
| Weeks of battery remaining | 16 |
| Spectrum: FrequencyBin | 17 |
| Spectrum: Direction | 18 |
| Spectrum: Spread | 19 |
| Spectrum: m2 | 20 |
| Spectrum: n2 | 21 |
| Spectrum: RPSD | 22 |
| Spectrum: K | 23 |
Channels 17-23 are only output if the spectrum option is enabled.
MQTT Source Options
type=MQTT
It is possible to read topics from a MQTT server and convert the values found into channels to be recorded by the logging software. This can be useful to interface with existing data collection software where duplicate instrumentation may not be viable. It should be noted that additional latency will be introduced by both the network connection, MQTT server, and the software used to feed data to it. This may need to be adjusted for when analysing the data after recording.
The MQTT system allows a server to mediate between multiple clients. Messages are exchanged between clients publishing messages to a named topic and other clients subscribing to that same topic. Topics are arranged in a hierarchy, and it is possible to subscribe to a given topic and all others that fall underneath it in that hierarchy. The format of the individual messages is arbitrary, and this logging software supports only a limited number of formats.
The general configuration for a MQTT source is shown above, and uses the following parameters:
host- IP address or DNS name of the serverport- TCP port number. A default (1883) will be used if not provided.dumpall- Record unknown messages to file (see below)
In the default configuration, the logging software will subscribe to specific topics and map messages sent to those topics to individual channels. Any messages received for other topics will be discarded. If the dumpall option is enabled then any messages not listed in the configuration will be recorded to channel 3 (the raw data channel) as strings with the format "topic: value". This would be required if using wildcards to receive messages for a group of topics, as no channel number would be allocated to them.
Each topic to be recorded needs to be added to the source definition using the topic option. Optionally, a channel name and text mode flag can be set, each separated by a colon as shown in the examples above. Channel numbers are allocated dynamically, but would normally be allocated in the order listed in the configuration.
If specified, the channel name given will be added to the channel mapping file to allow data from each topic to be identified. If no channel name is specified then the topic will be used instead.
The text mode flag will cause that topic to be stored in the recorded data as text. If not set, non-numeric data will be discarded or may generate errors.
Victron Energy devices
Some Victron Energy systems allow data to be retrieved over MQTT locally, as described on their GitHub page. This does require a specific message to be published to keep the connection active, which can be enabled using these additional options.
victron_keepalives- Enable or disable these messagessysid- The Victron device's ID needs to be incorporated into the keepalive requestkeepalive_interval- Messages will be sent at this interval, which must be less than the timeout on the Victron device.
Timer source options
type=timer or type=tick
In addition to the default timer, additional time sources can be defined to create timestamps at other intervals. The minimum frequency is 1Hz and values are currently limited to integers.
Record only sources
The last two data sources are provided to allow capture and storage of arbitrary data without parsing or interpretation.
Network / TCP sources
host- IP address or host name to connect toport- TCP port to connect totimeout- Consider the connection lost if no data is received after this period (in seconds).minbytes- Only generate a message to be logged when at least this many bytes are availablemaxbytes- Maximum number of bytes to be included in a single message
In the absence of more details about the data being recorded, the minbytes and maxbytes parameters should be set to generate no more than `frequency` messages per second. It is also recommended to keep minbytes above 10 to avoid inflating the file size with excess message headers (~5 bytes per message).
Serial sources
port: Serial port name or path. See also device names.baud: Serial data baud rateminbytes- Only generate a message to be logged when at least this many bytes are availablemaxbytes- Maximum number of bytes to be included in a single message
As with the generic network source, the minbytes and maxbytes parameters should be set to generate no more than `frequency` messages per second. It is also recommended to keep minbytes above 10 to avoid inflating the file size with excess message headers (~5 bytes per message).
Example Configuration
Device Names
Most external devices are represented on a Linux machine by named files in the /dev directory (e.g. /dev/ttyUSB0 for a USB serial adapter, /dev/i2c-1 for an I2C interface). The names of many of these files are dynamic, and are assigned when devices are connected or when they are discovered during start up. This means that the numbered suffix may change if a device is unplugged and reconnected, and may change when the computer is rebooted. This is a particular problem for USB serial devices that may be used as data sources (i.e. anything starting /dev/tty).
Rather than use the short dynamically assigned names in configuration files, a stable name should be used. On Debian (and therefore Raspberry Pi OS) based devices, stable names can be found in /dev/serial/by-id/ with file names based on the make, model, and serial number of the serial interface (which may differ from the equipment serial number).
As a modified example from a real system:
The short names at the time this list was generated are shown at the end of the line.
Another option is to write udev rules to create custom names for each connected device. How to write these rules is outside the scope of this documentation.
Further reading
- Up: Logger configuration
- Prev: Logger core options
