Location

include/rid/location.h Location message handling per ASTM F3411-22a.

Example usage: 

    rid_location_t location;

    rid_location_init(&location);
    rid_location_set_operational_status(&location, RID_OPERATIONAL_STATUS_AIRBORNE);
    rid_location_set_height_type(&location, RID_HEIGHT_TYPE_ABOVE_TAKEOFF);
    rid_location_set_coordinates(&location, 62.683472, 21.974944);
    rid_location_set_geodetic_altitude(&location, 120.5f);
    rid_location_set_height(&location, 50.0f);
    rid_location_set_speed(&location, 15.5f);
    rid_location_set_vertical_speed(&location, 2.0f);
    rid_location_set_track_direction(&location, 45);
    rid_location_set_timestamp(&location, 12345);
    rid_location_set_horizontal_accuracy(&location, RID_HORIZONTAL_ACCURACY_10M);
    rid_location_set_vertical_accuracy(&location, RID_VERTICAL_ACCURACY_10M);
    rid_location_set_speed_accuracy(&location, RID_SPEED_ACCURACY_1MS);
    rid_location_set_timestamp_accuracy(&location, RID_TIMESTAMP_ACCURACY_0_1S);
    rid_location_set_pressure_altitude(&location, 101.3f);
    rid_location_set_baro_altitude_accuracy(&location, RID_VERTICAL_ACCURACY_3M);

    hexdump(&location, sizeof(location));

    rid_height_type_t height_type = rid_location_get_height_type(&location);
    rid_operational_status_t status = rid_location_get_operational_status(&location);
    uint16_t direction = rid_location_get_track_direction(&location);
    float speed = rid_location_get_speed(&location);
    float vspeed = rid_location_get_vertical_speed(&location);
    double latitude = rid_location_get_latitude(&location);
    double longitude = rid_location_get_longitude(&location);
    float pressure_alt = rid_location_get_pressure_altitude(&location);
    float geodetic_alt = rid_location_get_geodetic_altitude(&location);
    float height = rid_location_get_height(&location);
    rid_horizontal_accuracy_t h_accuracy = rid_location_get_horizontal_accuracy(&location);
    rid_vertical_accuracy_t v_accuracy = rid_location_get_vertical_accuracy(&location);
    rid_speed_accuracy_t s_accuracy = rid_location_get_speed_accuracy(&location);
    rid_vertical_accuracy_t baro_accuracy = rid_location_get_baro_altitude_accuracy(&location);
    uint16_t timestamp = rid_location_get_timestamp(&location);
    rid_timestamp_accuracy_t ts_accuracy = rid_location_get_timestamp_accuracy(&location);

    printf("Height Type:         %s\n", rid_height_type_to_string(height_type));
    printf("Status:              %s\n", rid_operational_status_to_string(status));
    printf("Direction:           %u deg\n", direction);
    printf("Speed:               %.1f m/s\n", (double)speed);
    printf("Vertical Speed:      %.1f m/s\n", (double)vspeed);
    printf("Latitude:            %.6f\n", latitude);
    printf("Longitude:           %.6f\n", longitude);
    printf("Pressure Alt:        %.1f m\n", (double)pressure_alt);
    printf("Geodetic Alt:        %.1f m\n", (double)geodetic_alt);
    printf("Height:              %.1f m\n", (double)height);
    printf("Horizontal Accuracy: %s\n", rid_horizontal_accuracy_to_string(h_accuracy));
    printf("Vertical Accuracy:   %s\n", rid_vertical_accuracy_to_string(v_accuracy));
    printf("Speed Accuracy:      %s\n", rid_speed_accuracy_to_string(s_accuracy));
    printf("Baro Accuracy:       %s\n", rid_vertical_accuracy_to_string(baro_accuracy));
    printf("Timestamp:           %u ds\n", timestamp);
    printf("Timestamp Accuracy:  %s\n", rid_timestamp_accuracy_to_string(ts_accuracy));

Structures and Types

Type Name
enum rid_ew_direction_t
East/West direction flag per ASTM F3411-22a.
enum rid_height_type_t
Height reference type per ASTM F3411-22a.
enum rid_horizontal_accuracy_t
Horizontal accuracy per ASTM F3411-22a.
struct rid_location_t
Location message structure per ASTM F3411-22a.
enum rid_operational_status_t
Operational status per ASTM F3411-22a.
enum rid_speed_accuracy_t
Speed accuracy per ASTM F3411-22a.
enum rid_timestamp_accuracy_t
Timestamp accuracy per ASTM F3411-22a.
enum rid_vertical_accuracy_t
Vertical accuracy per ASTM F3411-22a.

Functions

Type Name
const char * rid_height_type_to_string (rid_height_type_t type)
Convert height type to string representation.
const char * rid_horizontal_accuracy_to_string (rid_horizontal_accuracy_t accuracy)
Convert horizontal accuracy to string representation.
rid_vertical_accuracy_t rid_location_get_baro_altitude_accuracy (const rid_location_t *location)
Get the barometric altitude accuracy from a Location message.
float rid_location_get_geodetic_altitude (const rid_location_t *location)
Get the geodetic altitude from a Location message.
float rid_location_get_height (const rid_location_t *location)
Get the height from a Location message.
rid_height_type_t rid_location_get_height_type (const rid_location_t *location)
Get the height reference type from a Location message.
rid_horizontal_accuracy_t rid_location_get_horizontal_accuracy (const rid_location_t *location)
Get the horizontal position accuracy from a Location message.
double rid_location_get_latitude (const rid_location_t *location)
Get the latitude from a Location message.
double rid_location_get_longitude (const rid_location_t *location)
Get the longitude from a Location message.
rid_operational_status_t rid_location_get_operational_status (const rid_location_t *location)
Get the operational status from a Location message.
float rid_location_get_pressure_altitude (const rid_location_t *location)
Get the pressure altitude from a Location message.
float rid_location_get_speed (const rid_location_t *location)
Get the ground speed from a Location message.
rid_speed_accuracy_t rid_location_get_speed_accuracy (const rid_location_t *location)
Get the speed accuracy from a Location message.
uint16_t rid_location_get_timestamp (const rid_location_t *location)
Get the timestamp from a Location message.
rid_timestamp_accuracy_t rid_location_get_timestamp_accuracy (const rid_location_t *location)
Get the timestamp accuracy from a Location message.
uint16_t rid_location_get_track_direction (const rid_location_t *location)
Get the track direction from a Location message.
rid_vertical_accuracy_t rid_location_get_vertical_accuracy (const rid_location_t *location)
Get the vertical position accuracy from a Location message.
float rid_location_get_vertical_speed (const rid_location_t *location)
Get the vertical speed from a Location message.
int rid_location_init (rid_location_t *location)
Initialize a Location message structure.
int rid_location_set_baro_altitude_accuracy (rid_location_t *location, rid_vertical_accuracy_t accuracy)
Set the barometric altitude accuracy for a Location message.
int rid_location_set_coordinates (rid_location_t *location, double latitude, double longitude)
Set the latitude and longitude for a Location message.
int rid_location_set_geodetic_altitude (rid_location_t *location, float altitude_m)
Set the geodetic altitude for a Location message.
int rid_location_set_height (rid_location_t *location, float height_m)
Set the height for a Location message.
int rid_location_set_height_type (rid_location_t *location, rid_height_type_t type)
Set the height reference type for a Location message.
int rid_location_set_horizontal_accuracy (rid_location_t *location, rid_horizontal_accuracy_t accuracy)
Set the horizontal position accuracy for a Location message.
int rid_location_set_operational_status (rid_location_t *location, rid_operational_status_t status)
Set the operational status for a Location message.
int rid_location_set_pressure_altitude (rid_location_t *location, float altitude_m)
Set the pressure altitude for a Location message.
int rid_location_set_speed (rid_location_t *location, float speed_ms)
Set the ground speed for a Location message.
int rid_location_set_speed_accuracy (rid_location_t *location, rid_speed_accuracy_t accuracy)
Set the speed accuracy for a Location message.
int rid_location_set_timestamp (rid_location_t *location, uint16_t deciseconds)
Set the timestamp for a Location message.
int rid_location_set_timestamp_accuracy (rid_location_t *location, rid_timestamp_accuracy_t accuracy)
Set the timestamp accuracy for a Location message.
int rid_location_set_track_direction (rid_location_t *location, uint16_t degrees)
Set the track direction for a Location message.
int rid_location_set_unixtime (rid_location_t *location, uint32_t unixtime)
Set the timestamp from Unix time for a Location message.
int rid_location_set_vertical_accuracy (rid_location_t *location, rid_vertical_accuracy_t accuracy)
Set the vertical position accuracy for a Location message.
int rid_location_set_vertical_speed (rid_location_t *location, float speed_ms)
Set the vertical speed for a Location message.
int rid_location_to_json (const rid_location_t *location, char *buffer, size_t buffer_size, size_t *needed_size)
Format a Location message as a JSON string.
int rid_location_validate (const rid_location_t *location)
Validate a Location message structure.
const char * rid_operational_status_to_string (rid_operational_status_t status)
Convert operational status to string representation.
const char * rid_speed_accuracy_to_string (rid_speed_accuracy_t accuracy)
Convert speed accuracy to string representation.
const char * rid_timestamp_accuracy_to_string (rid_timestamp_accuracy_t accuracy)
Convert timestamp accuracy to string representation.
const char * rid_vertical_accuracy_to_string (rid_vertical_accuracy_t accuracy)
Convert vertical accuracy to string representation.

Macros

Type Name
define RID_GEODETIC_ALTITUDE_INVALID FLT_MAX
Value indicating invalid geodetic altitude.
define RID_GEODETIC_ALTITUDE_INVALID_ENCODED 0
Encoded value for invalid geodetic altitude.
define RID_HEIGHT_INVALID FLT_MAX
Value indicating invalid height.
define RID_HEIGHT_INVALID_ENCODED 0
Encoded value for invalid height.
define RID_LATITUDE_INVALID DBL_MAX
Value indicating invalid latitude.
define RID_LONGITUDE_INVALID DBL_MAX
Value indicating invalid longitude.
define RID_PRESSURE_ALTITUDE_INVALID FLT_MAX
Value indicating invalid pressure altitude.
define RID_PRESSURE_ALTITUDE_INVALID_ENCODED 0
Encoded value for invalid pressure altitude.
define RID_SPEED_INVALID FLT_MAX
Value indicating invalid speed.
define RID_SPEED_INVALID_ENCODED 255
Encoded value for invalid speed.
define RID_TIMESTAMP_INVALID 0xFFFF
Value indicating invalid timestamp.
define RID_TIMESTAMP_MAX 36000
Maximum valid timestamp in deciseconds (1 hour).
define RID_TRACK_DIRECTION_MAX 359
Maximum valid track direction in degrees.
define RID_TRACK_DIRECTION_UNKNOWN 361
Value indicating unknown track direction.
define RID_TRACK_DIRECTION_UNKNOWN_ENCODED 181
Encoded value for unknown track direction.
define RID_VERTICAL_SPEED_INVALID FLT_MAX
Value indicating invalid vertical speed.
define RID_VERTICAL_SPEED_INVALID_ENCODED 126
Encoded value for invalid vertical speed.

Structures and Types Documentation

enum rid_ew_direction_t

East/West direction flag per ASTM F3411-22a.

enum rid_ew_direction_t {
    RID_EW_DIRECTION_EAST = 0,
    RID_EW_DIRECTION_WEST = 1
};

enum rid_height_type_t

Height reference type per ASTM F3411-22a.

enum rid_height_type_t {
    RID_HEIGHT_TYPE_ABOVE_TAKEOFF = 0,
    RID_HEIGHT_TYPE_AGL = 1
};

enum rid_horizontal_accuracy_t

Horizontal accuracy per ASTM F3411-22a.

enum rid_horizontal_accuracy_t {
    RID_HORIZONTAL_ACCURACY_UNKNOWN = 0,
    RID_HORIZONTAL_ACCURACY_18520M = 1,
    RID_HORIZONTAL_ACCURACY_7408M = 2,
    RID_HORIZONTAL_ACCURACY_3704M = 3,
    RID_HORIZONTAL_ACCURACY_1852M = 4,
    RID_HORIZONTAL_ACCURACY_926M = 5,
    RID_HORIZONTAL_ACCURACY_555M = 6,
    RID_HORIZONTAL_ACCURACY_185M = 7,
    RID_HORIZONTAL_ACCURACY_93M = 8,
    RID_HORIZONTAL_ACCURACY_30M = 9,
    RID_HORIZONTAL_ACCURACY_10M = 10,
    RID_HORIZONTAL_ACCURACY_3M = 11,
    RID_HORIZONTAL_ACCURACY_1M = 12,
    RID_HORIZONTAL_ACCURACY_MAX = 15
};

struct rid_location_t

Location message structure per ASTM F3411-22a.

Variables:

  • uint8_t baro_altitude_accuracy

  • uint8_t ew_direction

  • uint16_t geodetic_altitude

  • uint16_t height

  • uint8_t height_type

  • uint8_t horizontal_accuracy

  • int32_t latitude

  • int32_t longitude

  • uint8_t message_type

  • uint8_t operational_status

  • uint16_t pressure_altitude

  • uint8_t protocol_version

  • uint8_t reserved_1

  • uint8_t reserved_2

  • uint8_t reserved_3

  • uint8_t speed

  • uint8_t speed_accuracy

  • uint8_t speed_multiplier

  • uint16_t timestamp

  • uint8_t timestamp_accuracy

  • uint8_t track_direction

  • uint8_t vertical_accuracy

  • int8_t vertical_speed

enum rid_operational_status_t

Operational status per ASTM F3411-22a.

enum rid_operational_status_t {
    RID_OPERATIONAL_STATUS_UNDECLARED = 0,
    RID_OPERATIONAL_STATUS_GROUND = 1,
    RID_OPERATIONAL_STATUS_AIRBORNE = 2,
    RID_OPERATIONAL_STATUS_EMERGENCY = 3,
    RID_OPERATIONAL_STATUS_REMOTE_ID_SYSTEM_FAILURE = 4,
    RID_OPERATIONAL_STATUS_MAX = 15
};

enum rid_speed_accuracy_t

Speed accuracy per ASTM F3411-22a.

enum rid_speed_accuracy_t {
    RID_SPEED_ACCURACY_UNKNOWN = 0,
    RID_SPEED_ACCURACY_10MS = 1,
    RID_SPEED_ACCURACY_3MS = 2,
    RID_SPEED_ACCURACY_1MS = 3,
    RID_SPEED_ACCURACY_03MS = 4,
    RID_SPEED_ACCURACY_MAX = 15
};

enum rid_timestamp_accuracy_t

Timestamp accuracy per ASTM F3411-22a.

enum rid_timestamp_accuracy_t {
    RID_TIMESTAMP_ACCURACY_UNKNOWN = 0,
    RID_TIMESTAMP_ACCURACY_0_1S = 1,
    RID_TIMESTAMP_ACCURACY_0_2S = 2,
    RID_TIMESTAMP_ACCURACY_0_3S = 3,
    RID_TIMESTAMP_ACCURACY_0_4S = 4,
    RID_TIMESTAMP_ACCURACY_0_5S = 5,
    RID_TIMESTAMP_ACCURACY_0_6S = 6,
    RID_TIMESTAMP_ACCURACY_0_7S = 7,
    RID_TIMESTAMP_ACCURACY_0_8S = 8,
    RID_TIMESTAMP_ACCURACY_0_9S = 9,
    RID_TIMESTAMP_ACCURACY_1_0S = 10,
    RID_TIMESTAMP_ACCURACY_1_1S = 11,
    RID_TIMESTAMP_ACCURACY_1_2S = 12,
    RID_TIMESTAMP_ACCURACY_1_3S = 13,
    RID_TIMESTAMP_ACCURACY_1_4S = 14,
    RID_TIMESTAMP_ACCURACY_1_5S = 15
};

enum rid_vertical_accuracy_t

Vertical accuracy per ASTM F3411-22a.

enum rid_vertical_accuracy_t {
    RID_VERTICAL_ACCURACY_UNKNOWN = 0,
    RID_VERTICAL_ACCURACY_150M = 1,
    RID_VERTICAL_ACCURACY_45M = 2,
    RID_VERTICAL_ACCURACY_25M = 3,
    RID_VERTICAL_ACCURACY_10M = 4,
    RID_VERTICAL_ACCURACY_3M = 5,
    RID_VERTICAL_ACCURACY_1M = 6,
    RID_VERTICAL_ACCURACY_MAX = 15
};

Functions Documentation

function rid_height_type_to_string

Convert height type to string representation.

const char * rid_height_type_to_string (
    rid_height_type_t type
)

Parameters:

  • type The height type to convert.

Returns:

String representation of the height type. Returns "UNKNOWN" for invalid values.

function rid_horizontal_accuracy_to_string

Convert horizontal accuracy to string representation.

const char * rid_horizontal_accuracy_to_string (
    rid_horizontal_accuracy_t accuracy
)

Parameters:

  • accuracy The horizontal accuracy to convert.

Returns:

String representation of the horizontal accuracy. Returns "UNKNOWN" for invalid values.

function rid_location_get_baro_altitude_accuracy

Get the barometric altitude accuracy from a Location message.

rid_vertical_accuracy_t rid_location_get_baro_altitude_accuracy (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

The barometric altitude accuracy or RID_VERTICAL_ACCURACY_UNKNOWN if location is NULL.

function rid_location_get_geodetic_altitude

Get the geodetic altitude from a Location message.

float rid_location_get_geodetic_altitude (
    const rid_location_t *location
)

This is the GNSS height above or below the WGS-84 reference ellipsoid. In layman's terms, this is the height you get from you GPS.

Parameters:

  • location Pointer to the Location message structure.

Returns:

Geodetic altitude in meters or RID_GEODETIC_ALTITUDE_INVALID if location is NULL.

function rid_location_get_height

Get the height from a Location message.

float rid_location_get_height (
    const rid_location_t *location
)

This is an altitude relative to a local reference point which is either the takeoff location or above ground level. The reference point is set separately with rid_location_set_height_type() function.

Parameters:

  • location Pointer to the Location message structure.

Returns:

Height in meters or RID_HEIGHT_INVALID if location is NULL.

function rid_location_get_height_type

Get the height reference type from a Location message.

rid_height_type_t rid_location_get_height_type (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

The height reference type or RID_HEIGHT_TYPE_ABOVE_TAKEOFF if location is NULL.

function rid_location_get_horizontal_accuracy

Get the horizontal position accuracy from a Location message.

rid_horizontal_accuracy_t rid_location_get_horizontal_accuracy (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

The horizontal accuracy or RID_HORIZONTAL_ACCURACY_UNKNOWN if location is NULL.

function rid_location_get_latitude

Get the latitude from a Location message.

double rid_location_get_latitude (
    const rid_location_t *location
)

Returns RID_LATITUDE_INVALID when both latitude and longitude are zero.

Parameters:

  • location Pointer to the Location message structure.

Returns:

Latitude in degrees or RID_LATITUDE_INVALID if location is NULL or if both encoded latitude and longitude are 0.

function rid_location_get_longitude

Get the longitude from a Location message.

double rid_location_get_longitude (
    const rid_location_t *location
)

Returns RID_LONGITUDE_INVALID when both latitude and longitude are zero.

Parameters:

  • location Pointer to the Location message structure.

Returns:

Longitude in degrees or RID_LONGITUDE_INVALID if location is NULL or if both encoded latitude and longitude are 0.

function rid_location_get_operational_status

Get the operational status from a Location message.

rid_operational_status_t rid_location_get_operational_status (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

The operational status or RID_OPERATIONAL_STATUS_UNDECLARED if location is NULL.

function rid_location_get_pressure_altitude

Get the pressure altitude from a Location message.

float rid_location_get_pressure_altitude (
    const rid_location_t *location
)

This is the uncorrected barometric altitude referenced to the standard atmosphere (29.92 inHg / 1013.25 mb). It is not corrected for the local altimeter setting. It is used as common reference for algorithms computing altitude differences between aircraft.

Parameters:

  • location Pointer to the Location message structure.

Returns:

Pressure altitude in meters or RID_PRESSURE_ALTITUDE_INVALID if location is NULL.

function rid_location_get_speed

Get the ground speed from a Location message.

float rid_location_get_speed (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

Speed in meters per second or RID_SPEED_INVALID if location is NULL.

function rid_location_get_speed_accuracy

Get the speed accuracy from a Location message.

rid_speed_accuracy_t rid_location_get_speed_accuracy (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

The speed accuracy or RID_SPEED_ACCURACY_UNKNOWN if location is NULL.

function rid_location_get_timestamp

Get the timestamp from a Location message.

uint16_t rid_location_get_timestamp (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

Time in deciseconds since the hour or RID_TIMESTAMP_INVALID if location is NULL.

function rid_location_get_timestamp_accuracy

Get the timestamp accuracy from a Location message.

rid_timestamp_accuracy_t rid_location_get_timestamp_accuracy (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

The timestamp accuracy or RID_TIMESTAMP_ACCURACY_UNKNOWN if location is NULL.

function rid_location_get_track_direction

Get the track direction from a Location message.

uint16_t rid_location_get_track_direction (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

Track direction in degrees (0-359) or RID_TRACK_DIRECTION_UNKNOWN, including when location is NULL.

function rid_location_get_vertical_accuracy

Get the vertical position accuracy from a Location message.

rid_vertical_accuracy_t rid_location_get_vertical_accuracy (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

The vertical accuracy or RID_VERTICAL_ACCURACY_UNKNOWN if location is NULL.

function rid_location_get_vertical_speed

Get the vertical speed from a Location message.

float rid_location_get_vertical_speed (
    const rid_location_t *location
)

Parameters:

  • location Pointer to the Location message structure.

Returns:

Vertical speed in meters per second or RID_VERTICAL_SPEED_INVALID if location is NULL.

function rid_location_init

Initialize a Location message structure.

int rid_location_init (
    rid_location_t *location
)

Sets protocol version to RID_PROTOCOL_VERSION_2 and message type to RID_MESSAGE_TYPE_LOCATION. All other fields are set to invalid markers.

Parameters:

  • location Pointer to the Location message structure to initialize.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_baro_altitude_accuracy

Set the barometric altitude accuracy for a Location message.

int rid_location_set_baro_altitude_accuracy (
    rid_location_t *location,
    rid_vertical_accuracy_t accuracy
)

Parameters:

  • location Pointer to the Location message structure.
  • accuracy The barometric altitude accuracy to set.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_coordinates

Set the latitude and longitude for a Location message.

int rid_location_set_coordinates (
    rid_location_t *location,
    double latitude,
    double longitude
)

Encodes both values per ASTM F3411-22a. Pass RID_LATITUDE_INVALID and RID_LONGITUDE_INVALID together to set the position as unknown. A mixed invalid and valid pair is rejected.

Parameters:

  • location Pointer to the Location message structure.
  • latitude Latitude in degrees (-90.0 to +90.0) or RID_LATITUDE_INVALID.
  • longitude Longitude in degrees (-180.0 to +180.0) or RID_LONGITUDE_INVALID.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.
  • RID_ERROR_INVALID_COMBINATION if only one of latitude or longitude is invalid.
  • RID_ERROR_INVALID_LATITUDE if latitude is outside the valid range.
  • RID_ERROR_INVALID_LONGITUDE if longitude is outside the valid range.

function rid_location_set_geodetic_altitude

Set the geodetic altitude for a Location message.

int rid_location_set_geodetic_altitude (
    rid_location_t *location,
    float altitude_m
)

Encodes the value per ASTM F3411-22a Table 7 with 0.5 m resolution. Pass RID_GEODETIC_ALTITUDE_INVALID to mark the altitude as unknown.

This is the GNSS height above or below the WGS-84 reference ellipsoid. In layman's terms, this is the height you get from you GPS.

Parameters:

  • location Pointer to the Location message structure.
  • altitude_m Geodetic altitude in meters (-1000 to 31767), or RID_GEODETIC_ALTITUDE_INVALID for unknown.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.
  • RID_ERROR_OUT_OF_RANGE if altitude_m is outside the valid range.

function rid_location_set_height

Set the height for a Location message.

int rid_location_set_height (
    rid_location_t *location,
    float height_m
)

This is an altitude relative to a local reference point which is either the takeoff location or above ground level. The reference point is set separately with rid_location_set_height_type() function.

Encodes the value per ASTM F3411-22a Table 7 with 0.5 m resolution. Pass RID_HEIGHT_INVALID to mark the height as unknown.

Parameters:

  • location Pointer to the Location message structure.
  • height_m Height in meters (-1000 to 31767), or RID_HEIGHT_INVALID for unknown.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.
  • RID_ERROR_OUT_OF_RANGE if height_m is outside the valid range.

function rid_location_set_height_type

Set the height reference type for a Location message.

int rid_location_set_height_type (
    rid_location_t *location,
    rid_height_type_t type
)

Parameters:

  • location Pointer to the Location message structure.
  • type The height reference type to set.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_horizontal_accuracy

Set the horizontal position accuracy for a Location message.

int rid_location_set_horizontal_accuracy (
    rid_location_t *location,
    rid_horizontal_accuracy_t accuracy
)

Parameters:

  • location Pointer to the Location message structure.
  • accuracy The horizontal accuracy to set.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_operational_status

Set the operational status for a Location message.

int rid_location_set_operational_status (
    rid_location_t *location,
    rid_operational_status_t status
)

Parameters:

  • location Pointer to the Location message structure.
  • status The operational status to set.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_pressure_altitude

Set the pressure altitude for a Location message.

int rid_location_set_pressure_altitude (
    rid_location_t *location,
    float altitude_m
)

Encodes the value per ASTM F3411-22a Table 7 with 0.5 m resolution. Pass RID_PRESSURE_ALTITUDE_INVALID to mark the altitude as unknown.

This is the uncorrected barometric altitude referenced to the standard atmosphere (29.92 inHg / 1013.25 mb). It is not corrected for the local altimeter setting. It is used as common reference for algorithms computing altitude differences between aircraft.

Parameters:

  • location Pointer to the Location message structure.
  • altitude_m Pressure altitude in meters (-1000 to 31767) or RID_PRESSURE_ALTITUDE_INVALID for unknown.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.
  • RID_ERROR_OUT_OF_RANGE if altitude_m is outside the valid range.

function rid_location_set_speed

Set the ground speed for a Location message.

int rid_location_set_speed (
    rid_location_t *location,
    float speed_ms
)

Values above 254.25 m/s are clamped to 254.25 m/s.

Parameters:

  • location Pointer to the Location message structure.
  • speed_ms Speed in meters per second (0 to 254.25).

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.
  • RID_ERROR_OUT_OF_RANGE if speed_ms is negative.

function rid_location_set_speed_accuracy

Set the speed accuracy for a Location message.

int rid_location_set_speed_accuracy (
    rid_location_t *location,
    rid_speed_accuracy_t accuracy
)

Parameters:

  • location Pointer to the Location message structure.
  • accuracy The speed accuracy to set.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_timestamp

Set the timestamp for a Location message.

int rid_location_set_timestamp (
    rid_location_t *location,
    uint16_t deciseconds
)

Parameters:

  • location Pointer to the Location message structure.
  • deciseconds Time in deciseconds since the hour.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_timestamp_accuracy

Set the timestamp accuracy for a Location message.

int rid_location_set_timestamp_accuracy (
    rid_location_t *location,
    rid_timestamp_accuracy_t accuracy
)

Parameters:

  • location Pointer to the Location message structure.
  • accuracy The timestamp accuracy to set.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_track_direction

Set the track direction for a Location message.

int rid_location_set_track_direction (
    rid_location_t *location,
    uint16_t degrees
)

Parameters:

  • location Pointer to the Location message structure.
  • degrees Track direction in degrees (0-359) or RID_TRACK_DIRECTION_UNKNOWN.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_unixtime

Set the timestamp from Unix time for a Location message.

int rid_location_set_unixtime (
    rid_location_t *location,
    uint32_t unixtime
)

Converts Unix timestamp to deciseconds since the hour.

Parameters:

  • location Pointer to the Location message structure.
  • unixtime Unix timestamp (seconds since epoch).

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_vertical_accuracy

Set the vertical position accuracy for a Location message.

int rid_location_set_vertical_accuracy (
    rid_location_t *location,
    rid_vertical_accuracy_t accuracy
)

Parameters:

  • location Pointer to the Location message structure.
  • accuracy The vertical accuracy to set.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_set_vertical_speed

Set the vertical speed for a Location message.

int rid_location_set_vertical_speed (
    rid_location_t *location,
    float speed_ms
)

Values outside -62 to 62 m/s range are clamped to the nearest limit.

Parameters:

  • location Pointer to the Location message structure.
  • speed_ms Vertical speed in meters per second (-62 to 62).

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL.

function rid_location_to_json

Format a Location message as a JSON string.

int rid_location_to_json (
    const rid_location_t *location,
    char *buffer,
    size_t buffer_size,
    size_t *needed_size
)

Parameters:

  • location Pointer to the Location message structure.
  • buffer Buffer to store the JSON string or NULL.
  • buffer_size Size of the buffer.
  • needed_size If non-NULL receives the required buffer size.

Return value:

  • RID_SUCCESS on success.
  • RID_ERROR_NULL_POINTER if location is NULL or if bothbuffer andneeded_size are NULL.
  • RID_ERROR_BUFFER_TOO_SMALL if buffer is too small.

function rid_location_validate

Validate a Location message structure.

int rid_location_validate (
    const rid_location_t *location
)

Checks that all fields contain valid encoded values according to ASTM F3411-22a. This validates the raw encoded values, not decoded physical values.

Parameters:

  • location Pointer to the Location message structure to validate.

Return value:

  • RID_SUCCESS if all fields are valid.
  • RID_ERROR_NULL_POINTER if location is NULL.
  • RID_ERROR_INVALID_PROTOCOL_VERSION if protocol version is invalid.
  • RID_ERROR_UNKNOWN_MESSAGE_TYPE if message type is not LOCATION.
  • RID_ERROR_INVALID_LATITUDE if latitude is out of range.
  • RID_ERROR_INVALID_LONGITUDE if longitude is out of range.
  • RID_ERROR_INVALID_TRACK_DIRECTION if track direction is out of range.
  • RID_ERROR_INVALID_TIMESTAMP if timestamp is out of range.

function rid_operational_status_to_string

Convert operational status to string representation.

const char * rid_operational_status_to_string (
    rid_operational_status_t status
)

Parameters:

  • status The operational status to convert.

Returns:

String representation of the operational status. Returns "UNKNOWN" for invalid values.

function rid_speed_accuracy_to_string

Convert speed accuracy to string representation.

const char * rid_speed_accuracy_to_string (
    rid_speed_accuracy_t accuracy
)

Parameters:

  • accuracy The speed accuracy to convert.

Returns:

String representation of the speed accuracy. Returns "UNKNOWN" for invalid values.

function rid_timestamp_accuracy_to_string

Convert timestamp accuracy to string representation.

const char * rid_timestamp_accuracy_to_string (
    rid_timestamp_accuracy_t accuracy
)

Parameters:

  • accuracy The timestamp accuracy to convert.

Returns:

String representation of the timestamp accuracy. Returns "UNKNOWN" for invalid values.

function rid_vertical_accuracy_to_string

Convert vertical accuracy to string representation.

const char * rid_vertical_accuracy_to_string (
    rid_vertical_accuracy_t accuracy
)

Parameters:

  • accuracy The vertical accuracy to convert.

Returns:

String representation of the vertical accuracy. Returns "UNKNOWN" for invalid values.

Macros Documentation

define RID_GEODETIC_ALTITUDE_INVALID

Value indicating invalid geodetic altitude.

#define RID_GEODETIC_ALTITUDE_INVALID FLT_MAX

define RID_GEODETIC_ALTITUDE_INVALID_ENCODED

Encoded value for invalid geodetic altitude.

#define RID_GEODETIC_ALTITUDE_INVALID_ENCODED 0

define RID_HEIGHT_INVALID

Value indicating invalid height.

#define RID_HEIGHT_INVALID FLT_MAX

define RID_HEIGHT_INVALID_ENCODED

Encoded value for invalid height.

#define RID_HEIGHT_INVALID_ENCODED 0

define RID_LATITUDE_INVALID

Value indicating invalid latitude.

#define RID_LATITUDE_INVALID DBL_MAX

define RID_LONGITUDE_INVALID

Value indicating invalid longitude.

#define RID_LONGITUDE_INVALID DBL_MAX

define RID_PRESSURE_ALTITUDE_INVALID

Value indicating invalid pressure altitude.

#define RID_PRESSURE_ALTITUDE_INVALID FLT_MAX

define RID_PRESSURE_ALTITUDE_INVALID_ENCODED

Encoded value for invalid pressure altitude.

#define RID_PRESSURE_ALTITUDE_INVALID_ENCODED 0

define RID_SPEED_INVALID

Value indicating invalid speed.

#define RID_SPEED_INVALID FLT_MAX

define RID_SPEED_INVALID_ENCODED

Encoded value for invalid speed.

#define RID_SPEED_INVALID_ENCODED 255

define RID_TIMESTAMP_INVALID

Value indicating invalid timestamp.

#define RID_TIMESTAMP_INVALID 0xFFFF

define RID_TIMESTAMP_MAX

Maximum valid timestamp in deciseconds (1 hour).

#define RID_TIMESTAMP_MAX 36000

define RID_TRACK_DIRECTION_MAX

Maximum valid track direction in degrees.

#define RID_TRACK_DIRECTION_MAX 359

define RID_TRACK_DIRECTION_UNKNOWN

Value indicating unknown track direction.

#define RID_TRACK_DIRECTION_UNKNOWN 361

define RID_TRACK_DIRECTION_UNKNOWN_ENCODED

Encoded value for unknown track direction.

#define RID_TRACK_DIRECTION_UNKNOWN_ENCODED 181

define RID_VERTICAL_SPEED_INVALID

Value indicating invalid vertical speed.

#define RID_VERTICAL_SPEED_INVALID FLT_MAX

define RID_VERTICAL_SPEED_INVALID_ENCODED

Encoded value for invalid vertical speed.

#define RID_VERTICAL_SPEED_INVALID_ENCODED 126