Run the simulator headless

The command-line tool runs the full simulation without a display. Typical uses are feeding a chart plotter on another machine, generating test data in CI, or producing a log file.

Feed a chart plotter over TCP

1. Find the address of this machine: nmeasim interfaces.
2. Start the stream: nmeasim run --tcp-server 10110.
3. In the plotter, add a TCP connection to that address on port 10110. OpenCPN: Options → Connections → Add Connection → Network, TCP, port 10110.
4. Stop with Ctrl+C.

Broadcast to every device on the network

nmeasim run --udp 255.255.255.255:10110

To send from a specific interface, or to derive the subnet broadcast address instead of the limited one, use a profile with a udp output whose interface names the interface and whose address is empty.

Save a profile and tune it

nmeasim profile init harbour.json

Edit the file (see the profile reference), then:

nmeasim run --profile harbour.json

Command-line output options replace the profile's outputs for that run, so the same profile can go to TCP in one run and to a serial port in the next.

Follow a recorded track

nmeasim run --track samples/saronic-gulf.gpx --tcp-server 10110

The vessel sails the GPX or KML file on its own timestamps and the run ends at the last point. Add --loop to sail it again and again, --speed 8 --ignore-timestamps to sail it at a set speed, or use a route file without timestamps, which is always sailed at --speed. See Follow a track for the details and the profile keys.

Serve Signal K or drive Google Earth

nmeasim run --websocket 3000 --encoding signalk
nmeasim run --udp 192.168.1.20:42000 --encoding viewsync

--encoding applies to every output given on the command line; a profile mixes encodings per output. See Connect a Signal K server and Follow the vessel in Google Earth.

Steer for a waypoint

nmeasim run --tcp-server 10110 --destination 37.7466,23.4275,AEGINA

APB, RMB and XTE describe the leg from the start position to the waypoint; without a destination they are not sent.

Record a session

nmeasim run --record monday.log --tcp-server 10110 --duration 3600

--record writes every sentence with a timestamp to the file, in addition to the outputs; the file is truncated at the start. To record only some sentences, use a profile with a log output and a filter instead.

Replay a log

nmeasim run --replay monday.log --tcp-server 10110

The sentences are sent again, unchanged, on their original cadence, and the run ends when the log does. A log captured by another program works the same way: lines that carry a timestamp use it, lines that do not are timed from the RMC, GGA, GLL or ZDA time fields, and a log without any time information is played at a fixed interval (--replay-interval). The log file reference lists the accepted line shapes.

Generate a fixture for automated tests

nmeasim run --stdout --quiet --duration 10 --rate 1000 > fixture.nmea

With start_time set in the profile, the time fields are the same in every run; the drifting values follow the random seed but integrate real step lengths, so their last digit can differ between runs. Record a fixture once and commit it; the tutorial Building a test fixture from a recorded log walks through it.

Validate the stream with an independent parser

The repository ships tools/check_nmea_stream.py, which checks every sentence with the third-party pynmea2 parser:

pip install pynmea2
nmeasim run --stdout --quiet --duration 3 | python3 tools/check_nmea_stream.py --expect 21

CI runs this on every platform, together with tools/check_ais_stream.py (pyais), tools/check_signalk_stream.py and tools/check_viewsync_stream.py.

Run in the background on Linux

nohup nmeasim run --profile harbour.json --quiet > /dev/null 2> nmeasim.err &

The tool stops cleanly on SIGINT and SIGTERM, so kill %1 or a systemd unit with the default stop signal is enough.