DIY: Create a Tracker

with a Raspberry Pi, a USB GPS and/or an NMEA gateway


Raspberry Pi Python Linux GPS USB TCP UDP

This guide explains how to build your own Trakkit.org live tracker using a Raspberry Pi or any Linux system and Joli_Compagnon.

Compatible systems include:

  • Raspberry Pi OS
  • Ubuntu
  • Debian

Joli_Compagnon can read NMEA data from:

  • a USB GPS receiver, such as the BU-353N5
  • an NMEA multiplexer or gateway over TCP or UDP, such as the ShipModul Miniplex
  • both at the same time, for example the position from the USB GPS and the wind from the multiplexer

Table of Contents


Overview

Joli_Compagnon consists of two programs that run side by side:

  • reader.py listens to your data sources, decodes the NMEA sentences and stores them locally, with at most one position every 2 seconds.
  • sender.py compresses the stored data and uploads it to Trakkit.org over SFTP, every 5 minutes.

If the Internet connection is lost, the data stays on the Raspberry Pi and is sent as soon as the connection comes back.

The process is simple:

  1. Prepare your configuration on Trakkit.org
  2. Install Raspberry Pi OS
  3. Install and configure Joli_Compagnon
  4. Test the tracker
  5. Automate startup

⚓ - Configure your boat on Trakkit.org

Before installing anything on the Raspberry Pi, declare your tracker on Trakkit.org.

  1. Create your Boat
  2. Create a Tag
    (give it a recognizable name)
  3. Create a password for this Tag (Boat > Mails & Tags)
  4. Create a Track with:
    • Start date: 01/01/2020
    • End date: 01/01/2050
  5. Mark this track as LiveTrack (Boat > Edit > Active LiveTrack)

You must have available:

TAG
TAG PASSWORD

These credentials will be used by the tracker.


🍓 - Install Raspberry Pi OS

Install Raspberry Pi OS normally on your SD card.

Follow the official instructions:

https://www.raspberrypi.com/software

There is no special configuration required.

You can choose the Desktop version, easier to configure, or Lite version if you are comfortable with Linux.


⚙️ — Basic system configuration

At first boot:

  1. Create a user (In this guide we assume the username pi)
  2. Configure normally:
    • language
    • keyboard
    • network (Wifi to access the Internet)

It is recommended to set the timezone to UTC.


🛰️ — Prepare your data source

Follow the section matching your equipment. If you use both a USB GPS and an NMEA gateway, follow both.

Whatever the source, your GPS must send RMC sentences: they are the only ones that carry the date, and no position is recorded without them.

USB GPS

Connect the GPS to the Raspberry Pi and check that it is detected:

dmesg | grep tty

Example output:

[  123.456789] usb 1-1.2: pl2303 converter now attached to ttyUSB0

The GPS is available on:

/dev/ttyUSB0

The user running Joli_Compagnon must have access to the serial port, which means being a member of the dialout group:

sudo usermod -a -G dialout $USER

Then log out and log in again.

You do not need to find the serial speed yourself: if no NMEA data is received with the configured port and speed, reader.py tries the other speeds (4800 to 115200 baud), then the other serial ports, and tells you what it found.

NMEA gateway over WiFi or LAN

Depending on the connection type (WiFi or LAN) of your NMEA gateway, obtain the following information from the manufacturer:

  • IP address
  • Port
  • Protocol (UDP or TCP)

Typically, the configuration looks like:

IP: 10.0.0.1
Port: 10110
Protocol: TCP

If you are using WiFi and your NMEA gateway is not accessible on the same network as your main Internet connection, you may need to configure a second WiFi interface on your Raspberry Pi using an additional USB WiFi dongle.

This allows you to: - receive the NMEA data stream (incoming route) - send position data to Trakkit.org (outgoing route)


📦 — Install Joli_Compagnon

Download the software from the Trakkit website:

Trakkit.org → About → Download Tools

Download the file:

joli_compagnon.tgz

Extract it in your home directory:

tar -xzf joli_compagnon.tgz

This creates the directory joli_compagnon_last, which contains in particular:

reader.py
sender.py
config.ini.EXAMPLE
requirements.txt
README.txt
data/

🐍 — Create the Python virtual environment

Move into the directory:

cd joli_compagnon_last

Create the Python virtual environment:

python3 -m venv venv

Activate it:

source venv/bin/activate

Install the required modules:

pip install -r requirements.txt

🔧 — Configure Joli_Compagnon

Create the configuration file from the example:

cp config.ini.EXAMPLE config.ini

Edit it:

nano config.ini

Trakkit credentials

###############################################
# 🔑 Your Trakkit.org login credentials
###############################################
[USER]
TAG = YOUR_TAG_HERE
PWD = YOUR_TAG_PASSWORD_HERE

Data source

Choose the source in the READER section: usb, tcp or udp.

###############################################
# 🔀 Data source used by reader.py
###############################################
[READER]
SOURCE = usb

Several sources can be combined, separated by commas:

SOURCE = tcp, usb

The data of all sources is merged into a single track.

USB GPS (SOURCE = usb)

Set the device found earlier and its speed:

###############################################
# 🛰️ Data source from USB GPS device
###############################################
[GPS]
GPS_PORT = /dev/ttyUSB0
GPS_BAUDS = 4800

If the GPS is found on another port or at another speed, reader.py still uses it and displays the values to put here.

NMEA gateway over TCP (SOURCE = tcp)

Set the IP address and port of your gateway:

###############################################
# 📡 Data source from NMEA multiplexer
###############################################
[NMEA]
NMEA_SRV = 10.0.0.1
NMEA_PORT = 10110

NMEA gateway over UDP (SOURCE = udp)

With UDP, the gateway sends the data to the Raspberry Pi. NMEA_SRV is therefore the local address to listen on, not the address of the gateway:

  • 0.0.0.0 to receive from the network
  • 127.0.0.1 if the data comes from the Raspberry Pi itself

NMEA_PORT is the port your gateway sends to.

[NMEA]
NMEA_SRV = 0.0.0.0
NMEA_PORT = 10110

TCP and UDP share the NMEA section, so they cannot be used at the same time.

Other settings

These should be the only parameters you need to modify.

Do not set DELAY in the GENERAL section to less than 300 seconds, to avoid being banned by the Trakkit SFTP server for excessive usage or being considered as an attack.


🔁 — Manual launch of the tracker

Both programs must be started from the joli_compagnon_last directory, because config.ini and the data directory are looked up relative to the current directory.

Activate the Python virtual environment:

source venv/bin/activate

Start the reader:

./reader.py

You should see the NMEA sentences received:

📡 Listening to GPS on /dev/ttyUSB0 at 4800 baud
✅ Connected to GPS (/dev/ttyUSB0)
✅ $GPRMC,184551.00,A,4250.5589,N,07059.3421,W,0.13,309.62,210424,,,A*6C
✅ $GPGGA,184551.00,4250.5589,N,07059.3421,W,1,10,0.8,12.3,M,-33.9,M,,*5A
💾 written: 5 line(s)
  • ✅ marks a sentence used by Trakkit
  • ❌ marks a sentence ignored (unknown type, proprietary sentence or wrong checksum)
  • 💾 shows the positions saved locally, every 10 seconds

Start the sender in another terminal (activate the virtual environment there too):

./sender.py

This program sends the stored data to Trakkit.org every 5 minutes.

Wait a few minutes.

Your boat position should now appear on Trakkit.org.


🚀 - Automate startup with systemd

At this point, you now have a fully functional tracker for Trakkit.org. The final step is to configure it to start automatically at boot.

For the remainder of this guide, we assume the username pi and the following installation path:

/home/pi/joli_compagnon_last/

Scripts and virtual environment are located there.


Service for the reader

Create:

sudo nano /etc/systemd/system/trakkit_reader.service
[Unit]
Description=Trakkit.org Companion Reader
After=network.target

[Service]
User=pi
SupplementaryGroups=dialout
WorkingDirectory=/home/pi/joli_compagnon_last
Environment=PYTHONUNBUFFERED=1
ExecStart=/home/pi/joli_compagnon_last/venv/bin/python reader.py
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target

SupplementaryGroups=dialout gives access to the USB GPS. It is harmless if you only use an NMEA gateway.


Service for the sender

Create:

sudo nano /etc/systemd/system/trakkit_sender.service
[Unit]
Description=Trakkit.org Companion Sender
After=network.target

[Service]
User=pi
WorkingDirectory=/home/pi/joli_compagnon_last
Environment=PYTHONUNBUFFERED=1
ExecStart=/home/pi/joli_compagnon_last/venv/bin/python sender.py
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target

Enable the services

sudo systemctl daemon-reload
sudo systemctl enable --now trakkit_reader
sudo systemctl enable --now trakkit_sender

Check that they are running:

journalctl -u trakkit_reader -u trakkit_sender -f

Your Trakkit.org Companion will now start automatically at boot and send your boat position continuously.


🔄 — Upgrade from a previous version

Previous versions of Joli_Compagnon had one reader per source: reader_usb.py, reader_tcp.py and reader_udp.py. They are replaced by the single reader.py.

Stop the services:

sudo systemctl stop trakkit_reader trakkit_sender

Extract the new archive over the existing installation, from your home directory:

tar -xzf joli_compagnon.tgz

Your config.ini and your data are kept: the archive does not contain them.

Add the READER section to your config.ini, with the source you were using:

[READER]
SOURCE = usb

(usb if you used reader_usb.py, tcp for reader_tcp.py, udp for reader_udp.py).

Edit /etc/systemd/system/trakkit_reader.service so that it starts reader.py, as shown in Service for the reader, then restart:

sudo systemctl daemon-reload
sudo systemctl start trakkit_reader trakkit_sender

Data recorded by the previous version and not yet sent is sent as it is: nothing is lost.

You can then delete the old reader_usb.py, reader_tcp.py and reader_udp.py.