DIY: Create a Tracker
with a Raspberry Pi, a USB GPS and/or an NMEA gateway
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
- Configure your boat on Trakkit.org
- Install Raspberry Pi OS
- Basic system configuration
- Prepare your data source
- Install Joli_Compagnon
- Create the Python virtual environment
- Configure Joli_Compagnon
- Manual launch of the tracker
- Automate startup with systemd
- Upgrade from a previous version
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:
- Prepare your configuration on Trakkit.org
- Install Raspberry Pi OS
- Install and configure Joli_Compagnon
- Test the tracker
- Automate startup
⚓ - Configure your boat on Trakkit.org
Before installing anything on the Raspberry Pi, declare your tracker on Trakkit.org.
- Create your Boat
- Create a Tag
(give it a recognizable name) - Create a password for this Tag (Boat > Mails & Tags)
- Create a Track with:
- Start date: 01/01/2020
- End date: 01/01/2050
- 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:
- Create a user (In this guide we assume the username pi)
- 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.0to receive from the network127.0.0.1if 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.