nmeasim::core::signalk¶

namespace nmeasim::core::signalk · Library API

Signal K output, part of the nmeasim::core library.

It renders the vessel state as Signal K delta messages and the hello message, as one line of JSON each, without any JSON library: the documents are small and their shape is fixed. Values use the units of the specification (SI units and radians). Serving the messages over WebSocket or TCP is the job of nmeasim::io.

See also

https://signalk.org/specification/1.7.0/doc/

Types¶

Type	Description
`SignalKOptions`	Settings shared by the delta and hello encoders, one set per output.
`PathValue`	One path of a delta with its value already rendered as JSON.

Summary¶

Functions

Name	Description
`default_context()`	Returns the vessel context derived from the state's MMSI.
`effective_context()`	Returns the context used for an output.
`path_values()`	Returns every path the simulator publishes for the state, with its value.
`encode_delta()`	Encodes a delta message with one update carrying the selected paths.
`encode_hello()`	Encodes the hello message sent to a client when it connects.
`engine_id()`	Returns the Signal K identifier of an engine.
`json_string()`	Returns a JSON string literal for a text, quotes included.
`json_number()`	Returns a JSON number literal for a value.

Functions¶

default_context()¶

std::string default_context(const model::VesselState& state)

Returns the vessel context derived from the state's MMSI.

Parameters

Name	Type	Description
`state`	`const model::VesselState&`	Vessel state; only `state.ais.mmsi` is read.

Returns std::string: vessels.urn:mrn:imo:mmsi: followed by the MMSI in decimal.

See also

https://signalk.org/specification/1.7.0/doc/data_model.html

Declared in src/core/include/nmeasim/core/signalk/delta.hpp:52 · defined in src/core/src/signalk/delta.cpp:140

effective_context()¶

std::string effective_context(const SignalKOptions& options, const model::VesselState& state)

Returns the context used for an output.

Parameters

Name	Type	Description
`options`	`const SignalKOptions&`	Output settings.
`state`	`const model::VesselState&`	Vessel state, for the default context.

Returns std::string: options.context when it is not empty, otherwise default_context(state).

Declared in src/core/include/nmeasim/core/signalk/delta.hpp:59 · defined in src/core/src/signalk/delta.cpp:144

path_values()¶

std::vector<PathValue> path_values(const model::VesselState& state)

Returns every path the simulator publishes for the state, with its value.

Angles are in radians, rates of turn in radians per second, speeds in metres per second, lengths in metres, temperatures in kelvin and revolutions in hertz. Bearings are in [0, 2π), relative angles in (-π, π] positive to starboard, and positions are objects of longitude and latitude in degrees. Numbers are rounded to seven decimals.

Paths that need a GNSS fix (position, course and speed over ground, dilutions and antenna data) are left out without one; the navigation.courseRhumbline paths appear only with a destination; the environment.depth paths depend on the sign of the transducer offset; each engine adds three propulsion.<id> paths.

Parameters

Name	Type	Description
`state`	`const model::VesselState&`	Vessel state to publish.

Returns std::vector<PathValue>: The paths in a fixed order (navigation, environment, steering, propulsion), each path at most once.

See also

https://signalk.org/specification/1.7.0/doc/data_model.html

Declared in src/core/include/nmeasim/core/signalk/delta.hpp:78 · defined in src/core/src/signalk/delta.cpp:148

encode_delta()¶

std::string encode_delta(
    const model::VesselState& state,
    const SignalKOptions& options,
    const std::function<bool(std::string_view)>& admit = {})

Encodes a delta message with one update carrying the selected paths.

The update names the source by options.source_label with type simulator and is timestamped with the simulated clock state.time_utc.

Parameters

Name	Type	Description
`state`	`const model::VesselState&`	Vessel state to publish.
`options`	`const SignalKOptions&`	Context and source label.
`admit`	`const std::function<bool(std::string_view)>&`	Filter called with each path; a path is sent when it returns true. An empty function sends every path. A filter that admits nothing yields an empty `values` array.

Returns std::string: One JSON document without line terminator.

See also

https://signalk.org/specification/1.7.0/doc/data_model.html

Declared in src/core/include/nmeasim/core/signalk/delta.hpp:92 · defined in src/core/src/signalk/delta.cpp:246

encode_hello()¶

std::string encode_hello(
    const SignalKOptions& options,
    const model::VesselState& state,
    std::chrono::system_clock::time_point now)

Encodes the hello message sent to a client when it connects.

The message names this server by kProjectName and kVersion, gives the effective context as self and the roles master and main.

Parameters

Name	Type	Description
`options`	`const SignalKOptions&`	Output settings, for the context.
`state`	`const model::VesselState&`	Vessel state, for the default context.
`now`	`std::chrono::system_clock::time_point`	Wall-clock time of the connection, sent as `timestamp`.

Returns std::string: One JSON document without line terminator.

See also

https://signalk.org/specification/1.7.0/doc/streaming_api.html

Declared in src/core/include/nmeasim/core/signalk/delta.hpp:106 · defined in src/core/src/signalk/delta.cpp:264

engine_id()¶

std::string engine_id(std::string_view label, std::size_t index)

Returns the Signal K identifier of an engine.

The identifier is the <id> of the engine's propulsion.<id> paths. The label is reduced to the characters std::isalnum accepts (the ASCII letters and digits in the default locale), lower-cased, and its first occurrence of engine is removed: Port engine becomes port, Main-Diesel #2 becomes maindiesel2.

Parameters

Name	Type	Description
`label`	`std::string_view`	Engine label from the profile.
`index`	`std::size_t`	Zero-based position of the engine in `model::VesselState::engines`.

Returns std::string: The identifier, or engine followed by index + 1 when nothing is left of the label.

Declared in src/core/include/nmeasim/core/signalk/delta.hpp:121 · defined in src/core/src/signalk/delta.cpp:126

json_string()¶

std::string json_string(std::string_view text)

Returns a JSON string literal for a text, quotes included.

Quotes, backslashes and control characters are escaped: \n, \r and \t by name, the others as \u00XX. Bytes from 0x80 upwards are copied unchanged, so UTF-8 text passes through; invalid UTF-8 is not detected.

Parameters

Name	Type	Description
`text`	`std::string_view`	Text to quote.

Returns std::string: The JSON string literal.

Declared in src/core/include/nmeasim/core/signalk/delta.hpp:131 · defined in src/core/src/signalk/delta.cpp:77

json_number()¶

std::string json_number(double value)

Returns a JSON number literal for a value.

The value is rounded to seven decimals in fixed notation and trailing zeros are trimmed, so 12.0 becomes 12 and noise below the instruments' resolution disappears. Negative zero, including values that round to it, becomes 0.

Parameters

Name	Type	Description
`value`	`double`	Value to format.

Returns std::string: The number literal, or null when value is infinite or NaN.

Declared in src/core/include/nmeasim/core/signalk/delta.hpp:141 · defined in src/core/src/signalk/delta.cpp:107