Profile¶

struct nmeasim::io::Profile · Library API

A complete simulator setup, stored as a JSON profile file.

#include <nmeasim/io/profile/profile.hpp>

Declared in src/io/include/nmeasim/io/profile/profile.hpp (line 270)

A plain value type, copied freely. The initialisers of the fields, together with default_profile, give the defaults that from_json uses for missing keys.

See also

docs/reference/profile.md for every key, its default and its range.

Summary¶

Public member functions

Name	Description
`to_json()`	Serialises the profile at `kCurrentSchemaVersion`.
`save()`	Writes the profile as indented JSON, replacing the file atomically.
`resolve_path()`	Resolves a path of the profile against `base_directory`.
`make_scheduler()`	Builds a sentence scheduler with this profile's encoder options, sentence settings and custom sentences applied.

Public static member functions

Name	Description
`default_profile()`	Returns a ready-to-run profile: a vessel off Athens, every default sentence and one TCP server on port 10110.
`from_json()`	Parses a profile document, migrating an older schema version first.
`load()`	Reads and parses a profile file.

Public data members

Name	Description
`name`	Display name, the `name` key.
`tick_ms`	Length of one simulation tick in milliseconds, the `simulation.tick_ms` key; [10, 10000], a value outside is rejected.
`start_time`	Simulated start time in UTC, the `simulation.start_time` key; `std::nullopt` starts at the wall-clock time when the run starts.
`mode`	What drives the vessel, the `simulation.mode` key.
`delta`	The delta simulation, and the seed values for every mode.
`track`	Track-following settings, the `simulation.track` object; used in track mode.
`replay`	Log replay settings, the `simulation.replay` object; used in replay mode.
`encoder`	Encoder settings: `position_decimals` from the `sentences.position_decimals` key, [2, 8], a value outside is rejected.
`sentences`	Sentence settings that differ from the registry defaults, keyed by registry id; the `sentences.settings` object.
`custom_sentences`	Sentences typed in by the operator, in emission order; the `sentences.custom` array.
`outputs`	Output channels, the `outputs` array, in file order.
`base_directory`	Directory that the relative paths of the profile are relative to; not part of the JSON document.

Public static data members

Name	Description
`kCurrentSchemaVersion`	The schema version this code writes, the `schema_version` key.

Public member functions¶

to_json()¶

QJsonObject to_json() const

Serialises the profile at kCurrentSchemaVersion.

Every section is written in full, with the keys of each output limited to those its type and encoding use. A destination of std::nullopt is written as null.

Returns QJsonObject: The profile document, ready for QJsonDocument.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:349 · defined in src/io/src/profile/profile.cpp:958

save()¶

bool save(const QString& path, QString* error) const

Writes the profile as indented JSON, replacing the file atomically.

The document is written to a temporary file that replaces path only when everything was written, so a failure leaves an existing file untouched. Line endings are those of the platform. The paths are written as they are held, so a profile read by load is saved with its paths as the user wrote them. When base_directory is set and differs from the directory of path, the relative paths are rewritten relative to the new directory, so that they still name the same files; the profile itself is not changed.

Parameters

Name	Type	Description
`path`	`const QString&`	The file to write.
`error`	`QString*`	Receives `Cannot write` followed by the path and the system's reason when writing fails; left unchanged on success. May be null.

Returns bool: True when the file was written.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:396 · defined in src/io/src/profile/profile.cpp:1244

resolve_path()¶

QString resolve_path(const QString& path) const

Resolves a path of the profile against base_directory.

Parameters

Name	Type	Description
`path`	`const QString&`	A track, replay or output file path, as held in the profile.

Returns QString: path made absolute against base_directory and cleaned when it is relative and base_directory is set; otherwise path unchanged, which includes an empty path.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:404 · defined in src/io/src/profile/profile.cpp:1237

make_scheduler()¶

core::simulation::SentenceScheduler make_scheduler() const

Builds a sentence scheduler with this profile's encoder options, sentence settings and custom sentences applied.

Returns core::simulation::SentenceScheduler: The scheduler; registry sentences without a setting keep their defaults.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:410 · defined in src/io/src/profile/profile.cpp:1278

Public static member functions¶

default_profile()¶

static Profile default_profile()

Returns a ready-to-run profile: a vessel off Athens, every default sentence and one TCP server on port 10110.

The seed is at 37.9838 N, 23.7275 E heading 45 degrees true at 6.5 knots, with 12.4 m of depth, a 12-knot westerly wind and two engines running at 1800 rpm. It is the profile that nmeasim profile init writes.

Returns Profile: The default profile.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:341 · defined in src/io/src/profile/profile.cpp:935

from_json()¶

static std::optional<Profile> from_json(const QJsonObject& json, QString* error)

Parses a profile document, migrating an older schema version first.

Missing keys take the defaults of default_profile, except that the outputs default to none. A value of the wrong JSON type, or a fractional number for an integer key, is mostly treated as missing; a non-array simulation.seed.engines gives no engines and a non-object simulation.seed.destination gives none. simulation.random_seed ([0, 4294967295]) and simulation.seed.ais.mmsi and imo_number ([0, 999999999]) are the exception: a number that is negative, too large or not whole is rejected. Reading stops at the first problem: a missing, non-positive or too new schema_version, an unknown simulation mode, output type, encoding, UDP mode or sentence id, a value outside its range, a missing required path or serial port name, or an invalid custom sentence or AIS value. Paths are kept as they are written, and base_directory stays empty.

Parameters

Name	Type	Description
`json`	`const QJsonObject&`	The profile document.
`error`	`QString*`	Receives a message naming the offending key when parsing fails, such as `outputs[0]: unknown type 'x'`; left unchanged on success. May be null.

Returns std::optional<Profile>: The profile, or std::nullopt when the document is invalid.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:368 · defined in src/io/src/profile/profile.cpp:1022

load()¶

static std::optional<Profile> load(const QString& path, QString* error)

Reads and parses a profile file.

The paths are kept as written, and base_directory is set to the absolute directory that contains the file, against which resolve_path resolves the relative ones.

Parameters

Name	Type	Description
`path`	`const QString&`	The profile file.
`error`	`QString*`	Receives the reason when loading fails: `Cannot read` followed by the path and the system's reason, the path followed by `is not a JSON object` and the parser's message, or the message of `from_json`. Left unchanged on success. May be null.

Returns std::optional<Profile>: The profile, or std::nullopt when the file cannot be read, is not a JSON object or is not a valid profile.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:382 · defined in src/io/src/profile/profile.cpp:1216

Public data members¶

name¶

QString name{QStringLiteral("Default")}

Display name, the name key.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:280

tick_ms¶

int tick_ms{100}

Length of one simulation tick in milliseconds, the simulation.tick_ms key; [10, 10000], a value outside is rejected.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:283

start_time¶

std::optional<QDateTime> start_time

Simulated start time in UTC, the simulation.start_time key; std::nullopt starts at the wall-clock time when the run starts.

The key holds now (written for std::nullopt) or an ISO 8601 date-time with milliseconds, written in UTC such as 2026-09-22T12:34:56.780Z. A value read without a time zone is taken as local time and converted to UTC.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:290

mode¶

SimulationMode mode{SimulationMode::Delta}

What drives the vessel, the simulation.mode key.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:292

delta¶

core::simulation::DeltaConfig delta

The delta simulation, and the seed values for every mode.

Read from simulation.random_seed, simulation.seed, simulation.variation and simulation.steering. When read, a simulation.seed.gnss.quality other than invalid, gps or differential and a simulation.seed.destination object without numeric latitude and longitude are rejected. In track and replay mode the seed supplies the values the file does not carry and the variations are unused.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:300

track¶

TrackSettings track

Track-following settings, the simulation.track object; used in track mode.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:302

replay¶

ReplaySettings replay

Log replay settings, the simulation.replay object; used in replay mode.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:304

encoder¶

core::nmea0183::EncoderOptions encoder

Encoder settings: position_decimals from the sentences.position_decimals key, [2, 8], a value outside is rejected.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:307

sentences¶

std::map<std::string, core::simulation::SentenceSetting> sentences

Sentence settings that differ from the registry defaults, keyed by registry id; the sentences.settings object.

Reading an id the registry does not know is an error. A key missing from an entry takes the registry default. When read, a talker must be empty or two upper-case letters and period_ms must lie in [50, 3600000].

Declared in src/io/include/nmeasim/io/profile/profile.hpp:314

custom_sentences¶

std::vector<core::simulation::CustomSentence> custom_sentences

Sentences typed in by the operator, in emission order; the sentences.custom array.

When read, an id is trimmed and upper-cased and must not be a registry id nor the id of another entry, the CUSTOM-n an entry without id stands for included (see core::simulation::find_duplicate_custom_id); the body must pass core::simulation::validate_custom_sentence; period_ms must lie in [50, 3600000].

Declared in src/io/include/nmeasim/io/profile/profile.hpp:321

outputs¶

QList<OutputConfig> outputs

Output channels, the outputs array, in file order.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:323

base_directory¶

QString base_directory

Directory that the relative paths of the profile are relative to; not part of the JSON document.

load sets it to the absolute directory of the profile file, so that a profile can name the track, the log to replay and the output files next to it. Empty for a profile built in code or parsed with from_json: its relative paths are then used as they are, relative to the working directory of the process.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:331

Public static data members¶

kCurrentSchemaVersion¶

static int kCurrentSchemaVersion{3}

The schema version this code writes, the schema_version key.

Files with versions 1 and 2 are migrated when they are read; newer files are rejected. Version 2 added the track and replay modes and the log output type; version 3 added the destination and AIS seed data, custom sentences, and the Signal K and ViewSync encodings with TAG blocks.

Declared in src/io/include/nmeasim/io/profile/profile.hpp:277