nmeasim::core::ais

namespace nmeasim::core::ais · Library API

AIS messages of the own vessel as a class A station, part of the nmeasim::core library.

It packs the position report (message types 1, 2 and 3) and the static and voyage data report (message type 5) from the vessel state, armours them into six-bit ASCII and frames them as VDO or VDM sentences. Decoding received AIS traffic is not part of it.

See also

• ITU-R M.1371-5, Annex 8.

Types

Type	Description
BitPacker	Accumulates the bit fields of one AIS message, most significant bit first.
Payload	A packed payload ready for a sentence: the armoured characters and the fill bits.

Summary

Functions

Name	Description
pack_position_report()	Packs a class A position report from the state.
pack_static_data()	Packs a static and voyage data report (message type 5) from the state.
frame_payload()	Splits an armoured payload into the VDO or VDM sentences that carry it.
rate_of_turn_code()	Returns the AIS rate-of-turn code for a rate of turn.
heading_code()	Returns the AIS true heading code for a heading.
armor()	Armours a bit string into six-bit ASCII payload characters.
sixbit_code()	Returns the six-bit code of a character of the AIS text alphabet.
unarmor()	Returns the six-bit value an armoured payload character stands for.

Variables

Name	Description
kAisVersionIndicator	AIS version indicator sent in message 5: 2, a station compliant with ITU-R M.1371-5, the edition whose message layouts this module implements.
kRateOfTurnNotAvailable	Rate-of-turn code meaning "no turn information available", -128 (0x80).
kHeadingNotAvailable	True heading code meaning "not available", 511.

Functions

pack_position_report()

BitPacker pack_position_report(const model::VesselState& state)

Packs a class A position report from the state.

The fields and the values sent are:

• message type: state.ais.position_report_type when it is 1, 2 or 3, otherwise 1;
• repeat indicator 0, MMSI state.ais.mmsi (its low 30 bits);
• navigational status: state.ais.navigation_status clamped to [0, 15];
• rate of turn: rate_of_turn_code of the rate of turn;
• speed over ground in tenths of a knot, rounded and clamped to [0, 1022] (1022 means 102.2 kn or more); 1023, "not available", without a fix;
• position accuracy: 1 with a differential fix, 0 otherwise;
• longitude and latitude in 1/10000 minute, east and north positive; 181 and 91 degrees, "not available", without a fix;
• course over ground in tenths of a degree, rounded and clamped to [0, 3599]; 3600, "not available", without a fix;
• true heading: heading_code of the true heading, in [0, 359], or 511 ("not available") when the heading is not a finite number;
• time stamp: the UTC second of state.time_utc, in [0, 59];
• manoeuvre indicator 0 (not available), spare 0, RAIM flag 0, radio status 0.

Parameters

Name	Type	Description
state	const model::VesselState&	Vessel state to report; "without a fix" means state.gnss.has_fix is false.

Returns BitPacker: The 168 bits of the message.

See also

• ITU-R M.1371-5, Annex 8, messages 1, 2 and 3.

Declared in src/core/include/nmeasim/core/ais/messages.hpp:50 · defined in src/core/src/ais/messages.cpp:77

pack_static_data()

BitPacker pack_static_data(const model::VesselState& state)

Packs a static and voyage data report (message type 5) from the state.

The fields and the values sent are:

• repeat indicator 0, MMSI state.ais.mmsi, AIS version indicator kAisVersionIndicator (2, ITU-R M.1371-5, the edition whose layout is implemented);
• IMO number, call sign (7 characters) and name (20 characters) from state.ais, text upper-cased, padded with @ and truncated;
• type of ship and cargo: state.ais.ship_type clamped to [0, 255];
• dimensions in whole metres, rounded and clamped to [0, 511] towards bow and stern and to [0, 63] towards port and starboard;
• type of position fixing device 1 (GPS);
• ETA month 0, day 0, hour 24 and minute 60, all "not available";
• maximum static draught in tenths of a metre, clamped to [0, 25.5] m;
• destination, 20 characters, all @ when empty;
• DTE 0 (data terminal available) and one spare bit.

Parameters

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

Returns BitPacker: The 424 bits of the message.

See also

• ITU-R M.1371-5, Annex 8, message 5.

Declared in src/core/include/nmeasim/core/ais/messages.hpp:71 · defined in src/core/src/ais/messages.cpp:113

frame_payload()

std::vector<std::string> frame_payload(
    std::string_view talker,
    std::string_view formatter,
    const Payload& payload,
    int sequence)

Splits an armoured payload into the VDO or VDM sentences that carry it.

Each sentence carries at most 60 payload characters, so that every sentence stays within the 82-character limit of NMEA 0183: a position report fits one sentence, a static data report needs two. The fields are the total number of sentences, the number of this sentence from 1, the sequential message id (empty for a single sentence), the radio channel A, the payload fragment and the fill bits (0 in every sentence but the last). An empty payload still yields one sentence.

Parameters

Name	Type	Description
talker	std::string_view	Two-character talker identifier, normally AI.
formatter	std::string_view	Sentence formatter: VDO for the own vessel or VDM for a received target. It is not checked.
payload	const Payload&	Armoured payload as armor returns it.
sequence	int	Sequential message id shared by the sentences of a multi-sentence message, clamped to [0, 9]; ignored when one sentence suffices.

Returns std::vector<std::string>: The sentences in order, each starting with ! and ending with its checksum, without line terminator.

See also

• NMEA 0183 (IEC 61162-1), sentences VDM and VDO.

Declared in src/core/include/nmeasim/core/ais/messages.hpp:91 · defined in src/core/src/ais/messages.cpp:140

rate_of_turn_code()

int rate_of_turn_code(double rate_deg_per_min) noexcept

Returns the AIS rate-of-turn code for a rate of turn.

The code is 4.733 times the square root of the absolute rate, rounded, with the rate's sign: 0 to plus or minus 126, where 126 means 708 degrees per minute or more, as the standard codes the output of a turn indicator. The simulated rate of turn is such an output, so plus or minus 127 (turning faster than 5 degrees per 30 seconds, no turn indicator available) is never produced.

Parameters

Name	Type	Description
rate_deg_per_min	double	Rate of turn in degrees per minute, positive to starboard.

Returns int: The code in [-126, 126], positive to starboard; or kRateOfTurnNotAvailable (-128) when the rate is not a finite number.

See also

• ITU-R M.1371-5, Annex 8, message 1, field "rate of turn".

Declared in src/core/include/nmeasim/core/ais/messages.hpp:123 · defined in src/core/src/ais/messages.cpp:58

heading_code()

std::uint32_t heading_code(double heading_true_deg) noexcept

Returns the AIS true heading code for a heading.

Parameters

Name	Type	Description
heading_true_deg	double	Heading in degrees true, of any value; it is normalised to [0, 360) and rounded to whole degrees, so -10 gives 350 and 359.6 gives 0.

Returns std::uint32_t: The heading in [0, 359]; or kHeadingNotAvailable (511) when the heading is not a finite number.

See also

• ITU-R M.1371-5, Annex 8, message 1, field "true heading".

Declared in src/core/include/nmeasim/core/ais/messages.hpp:132 · defined in src/core/src/ais/messages.cpp:69

armor()

Payload armor(const std::vector<bool>& bits)

Armours a bit string into six-bit ASCII payload characters.

Each group of six bits, most significant first, becomes one character: values 0 to 39 map to 0-W (value plus 48) and 40 to 63 to `-w (value plus 56). A last group shorter than six bits is padded with zero bits on the right.

Parameters

Name	Type	Description
bits	const std::vector<bool>&	Message bits in transmission order, as BitPacker::bits returns them.

Returns Payload: The payload characters and the number of fill bits.

See also

• NMEA 0183 (IEC 61162-1), sentence VDM.

Declared in src/core/include/nmeasim/core/ais/sixbit.hpp:107 · defined in src/core/src/ais/sixbit.cpp:57

sixbit_code()

std::uint8_t sixbit_code(char c) noexcept

Returns the six-bit code of a character of the AIS text alphabet.

The alphabet is @, A-Z, [, \\endiskip, ], ^, _ (codes 0 to 31) followed by space and ! to ?, digits included (codes 32 to 63). Lower-case letters are upper-cased first.

Parameters

Name	Type	Description
c	char	Character to encode.

Returns std::uint8_t: The code in [0, 63]; 63, the code of ?, for any character outside the alphabet.

See also

• ITU-R M.1371-5, Annex 8, six-bit ASCII table.

Declared in src/core/include/nmeasim/core/ais/sixbit.hpp:118 · defined in src/core/src/ais/sixbit.cpp:46

unarmor()

int unarmor(char c) noexcept

Returns the six-bit value an armoured payload character stands for.

This is the inverse of the mapping armor applies.

Parameters

Name	Type	Description
c	char	Payload character.

Returns int: The value in [0, 63], or -1 when c is not in 0-W or `-w.

Declared in src/core/include/nmeasim/core/ais/sixbit.hpp:126 · defined in src/core/src/ais/sixbit.cpp:77

Variables

kAisVersionIndicator

std::uint32_t kAisVersionIndicator{2}

AIS version indicator sent in message 5: 2, a station compliant with ITU-R M.1371-5, the edition whose message layouts this module implements.

See also

• ITU-R M.1371-5, Annex 8, message 5, field "AIS version indicator".

Declared in src/core/include/nmeasim/core/ais/messages.hpp:99

kRateOfTurnNotAvailable

int kRateOfTurnNotAvailable{-128}

Rate-of-turn code meaning "no turn information available", -128 (0x80).

See also

• ITU-R M.1371-5, Annex 8, message 1, field "rate of turn".

Declared in src/core/include/nmeasim/core/ais/messages.hpp:104

kHeadingNotAvailable

std::uint32_t kHeadingNotAvailable{511}

True heading code meaning "not available", 511.

See also

• ITU-R M.1371-5, Annex 8, message 1, field "true heading".

Declared in src/core/include/nmeasim/core/ais/messages.hpp:109