NMEA-GPS Emulator

The NMEA-GPS Emulator is a simple script that emulates a GPS receiver (simulates unit's movement). Data generated by the script are sent to clients in NMEA 0183 format. This script can be useful for testing applications or systems that require some unit's GPS position data.

The NMEA-GPS Emulator script can be used in one of the following operating modes:

• NMEA TCP Stream (sends TCP packets to the specified client),
• NMEA UDP Stream (sends UDP packets to the specified client),
• NMEA TCP Server (the server waits for client connections, then sends TCP packets to the connected clients - max 10 connections)
• NMEA Serial (transmit serial data on specified RS port).

---

Features

• The script allows the user to enter the following data:
  • unit's position;
  • unit's speed;
  • unit's course;
  • operating mode selection (NMEA Serial, NMEA TCP Server, NMEA TCP or UDP Stream);
  • IP address & port pair or serial port name.
• After the NMEA data transmission has started, the script allows the user to interactively change the speed and course of the unit.
• Generated NMEA sentences are resent to the selected clients periodically (every second). Each time a data with NMEA sentences is sent, the position of the unit is updated based on its speed and course.

List of NMEA sentences generated by NMEA-GPS Emulator script:

GPGGA - Global Positioning System Fix Data
GPGLL - Position data: position fix, time of position fix, and status
GPRMC - Recommended minimum specific GPS/Transit data
GPGSA - GPS DOP and active satellites
GPGSV - GPS Satellites in view
GPHDT - True Heading
GPVTG - Track made good and ground speed
GPZDA - Date & Time

Output example:

$GPGGA,173124.00,5430.000,N,01921.029,E,1,09,0.92,15.2,M,32.5,M,,*6C
$GPGSA,A,3,22,11,27,01,03,02,10,21,19,,,,1.56,0.92,1.25*02
$GPGSV,4,1,15,26,25,138,53,16,25,091,67,01,51,238,77,02,45,085,41*79
$GPGSV,4,2,15,03,38,312,01,30,68,187,37,11,22,049,44,09,67,076,71*77
$GPGSV,4,3,15,10,14,177,12,19,86,235,37,21,84,343,95,22,77,040,66*79
$GPGSV,4,4,15,08,50,177,60,06,81,336,46,27,63,209,83*4C
$GPGLL,5430.000,N,01921.029,E,173124.000,A,A*59
$GPRMC,173124.000,A,5430.000,N,01921.029,E,10.500,90.0,051121,,,A*65
$GPHDT,90.0,T*0C
$GPVTG,90.0,T,,M,10.5,N,19.4,K*51
$GPZDA,173124.000,05,11,2021,0,0*50

---

How It Works

The emulator simulates realistic GPS receiver behavior through several key components:

Position Calculation

• Uses pyproj library for geodetic calculations on the WGS84 ellipsoid
• Calculates new positions based on current speed, heading, and time elapsed
• Converts between geographic coordinates (lat/lon) and projected coordinates for accurate distance calculations
• Updates position every second based on the unit's velocity vector

NMEA Sentence Generation

• Generates 8 standard NMEA 0183 sentences with proper formatting
• Calculates XOR checksums for each sentence to ensure data integrity
• Simulates realistic GPS data including:
  • Satellite information (GPGSV) with pseudo-random satellite positions and signal strengths
  • Dilution of Precision (DOP) values for position accuracy estimation
  • Time synchronization with system clock

Threading Architecture

• Main thread: Handles user input for interactive speed/course changes
• Worker threads: Manage client connections and data transmission
  • TCP Server mode: Accepts up to 10 concurrent client connections
  • TCP/UDP Stream mode: Maintains persistent connection to specified client
  • Serial mode: Transmits data via RS-232 serial port
• Thread-safe communication using events and locks for coordinated shutdown

Data Transmission

• Sends complete NMEA sentence sets every second
• Automatically updates position before each transmission
• Supports interactive runtime modifications of speed and heading without interrupting data flow

---

Getting Started

Below instructions will get you a copy of the project up and running on your local machine.

Requirements

Python 3.12 or higher is required. If your system has an older Python version, you can use pyenv to install and manage multiple Python versions:

# Install Python 3.12 with pyenv
pyenv install 3.12
pyenv local 3.12  # Set Python 3.12 for this project

Python third party packages:

• pyproj
• pyserial
• psutil

In order to use NMEA Serial mode correctly, it is necessary to use dedicated serial null modem cable.

On Linux systems you will probably need to change the permissions for the device matching your serial port before running the script.

# Example command for /dev/ttyUSB0 device
sudo chmod a+rw /dev/ttyUSB0

Installation

Option 1: Install from wheel file (Recommended)

Download the wheel file from the releases page and install it:

pip install nmea_gps_emulator-1.0.0-py3-none-any.whl

Option 2: Development installation

git clone https://github.com/luk-kop/nmea-gps-emulator.git
cd nmea-gps-emulator
python3.12 -m venv venv
source venv/bin/activate
pip install -e .

Running the application

If installed from wheel file:

nmea-gps-emulator

If using development installation:

python -m nmea_gps_emulator

Command-line options

The emulator supports the following command-line options to control output verbosity:

nmea-gps-emulator [OPTIONS]

Options:
  -h, --help     Show help message and exit
  -q, --quiet    Suppress informational messages (only show errors and user prompts)
  -v, --verbose  Enable verbose output with detailed debug information

Usage examples:

# Normal operation (default) - shows status messages and connection info
nmea-gps-emulator

# Quiet mode - minimal output, useful for scripts or automation
nmea-gps-emulator --quiet

# Verbose mode - detailed diagnostic information for troubleshooting
nmea-gps-emulator --verbose

Output modes:

• Default: Shows informational messages including server status, client connections, and configuration details
• Quiet mode (-q): Only displays user prompts, errors, and essential status messages. Ideal for automated environments or when you want minimal console output
• Verbose mode (-v): Displays detailed debug information including timing metrics, thread operations, and internal state changes. Useful for debugging and development

After starting the script correctly, the following prompt should appear in the OS console:

..####...#####....####...........######..##...##..##..##..##.......####...######...####...#####..
.##......##..##..##..............##......###.###..##..##..##......##..##....##....##..##..##..##.
.##.###..#####....####...........####....##.#.##..##..##..##......######....##....##..##..#####..
.##..##..##..........##..........##......##...##..##..##..##......##..##....##....##..##..##..##.
..####...##.......####...........######..##...##...####...######..##..##....##.....####...##..##.
.................................................................................................

### Choose emulator option: ###
1 - NMEA Serial
2 - NMEA TCP Server
3 - NMEA TCP or UDP Stream
4 - Quit
>>>

---

Contributing

Contributions are welcome! When creating a pull request, please ensure your branch name follows the naming convention:

Valid branch name prefixes:

• feature/ - New features
• fix/ or bugfix/ - Bug fixes
• hotfix/ - Urgent fixes
• docs/ - Documentation changes
• chore/ - Maintenance tasks
• refactor/ - Code refactoring
• test/ - Test additions or modifications
• ci/ - CI/CD changes
• release/ - Release preparation

Example: feature/add-nmea-sentence or fix/serial-port-timeout

Pull requests with branch names not following this convention will be rejected by CI validation.