Telematics SDK - Interface Specification  v1.38.19
C Kinematics APIs

Data Structures

struct  v2x_GNSSstatus_t
 
struct  v2x_gnss_fix_rates_supported_list_t
 
struct  v2x_init_t
 
struct  v2x_kinematics_capabilities_t_feature_flags_t
 
struct  v2x_rates_t
 
struct  v2x_kinematics_capabilities_t
 
struct  v2x_location_fix_t
 

Macros

#define V2X_KINEMATICS_HANDLE_BAD   (-1)
 

Typedefs

typedef int v2x_kinematics_handle_t
 
typedef void(* v2x_kinematics_init_callback_t) (v2x_status_enum_type status, void *context)
 
typedef void(* v2x_kinematics_rate_notification_listener_t) (v2x_status_enum_type status, v2x_rates_t *rate, void *ctx)
 
typedef void(* v2x_kinematics_set_rate_callback_t) (v2x_status_enum_type status, void *context)
 
typedef void(* v2x_kinematics_get_capability_callback_t) (v2x_kinematics_capabilities_t *cap, void *context)
 
typedef void(* v2x_kinematics_newfix_listener_t) (v2x_location_fix_t *new_fix, void *context)
 
typedef void(* v2x_kinematics_deregister_callback_t) (v2x_status_enum_type status, void *context)
 
typedef void(* v2x_kinematics_final_callback_t) (v2x_status_enum_type status, void *context)
 

Enumerations

enum  v2x_fix_mode_t { V2X_GNSS_MODE_NOT_SEEN = 0, V2X_GNSS_MODE_NO_FIX = 1, V2X_GNSS_MODE_2D = 2, V2X_GNSS_MODE_3D = 3 }
 

Functions

v2x_api_ver_t v2x_kinematics_api_version (void)
 
v2x_kinematics_handle_t v2x_kinematics_init (v2x_init_t *param, v2x_kinematics_init_callback_t cb, void *context)
 
v2x_status_enum_type v2x_kinematics_start_rate_notification (v2x_kinematics_handle_t handle, v2x_kinematics_rate_notification_listener_t cb, void *context)
 
v2x_status_enum_type v2x_kinematics_set_rate (v2x_kinematics_handle_t handle, v2x_rates_t *rate, v2x_kinematics_set_rate_callback_t cb, void *context)
 
v2x_status_enum_type v2x_kinematics_register_listener (v2x_kinematics_handle_t handle, v2x_kinematics_newfix_listener_t listener, void *context)
 
v2x_status_enum_type v2x_kinematics_deregister_listener (v2x_kinematics_handle_t handle, v2x_kinematics_deregister_callback_t cb, void *context)
 
v2x_status_enum_type v2x_kinematics_final (v2x_kinematics_handle_t handle, v2x_kinematics_final_callback_t cb, void *context)
 
void v2x_kinematics_enable_fixes (v2x_kinematics_handle_t handle)
 
void v2x_kinematics_disable_fixes (v2x_kinematics_handle_t handle)
 

Detailed Description

This section contains C Kinematics APIs related to Cellular-V2X operation. For any new CV2x development, it is recommended to use the C++ telux::loc::ILocationManager APIs.

Abstraction of the system GNSS + DR solution for returning precision fixes with low latency via callbacks. This solution is used each time a fix is available, and it supports multiple callbacks to a short list of clients.

Common types are used for the motion and location reporting system of the platform. These types include the structures that are used to both configure the Kinematics subsystem and to report periodic fixes. The fixes are combinations of inertial/motion data and GNSS solutions determined (possibly directly) from satellite processing or dead-reckoning in degraded SV reception.


Data Structure Documentation

struct v2x_GNSSstatus_t

Contains status information for the GNSS satellite.

This structure is used for each reported fix to indicate the quality of the available constellation (or whether the constellation is not available).

Data Fields
bool unavailable

Specifies whether a constellation is not equipped or is unavailable.

Supported values:
  • 0 – GNSS is available
  • 1 – GNSS is unavailable
bool aPDOPofUnder5

Specifies whether dilution of precision is greater than 5.

Supported values:
  • 0 – Not greater than 5
  • 1 – Greater than 5
bool inViewOfUnder5

Specifies whether fewer than five satellites are in view.

Supported values:
  • 0 – Five or more satellites are in view
  • 1 – Fewer than five satellites are in view
bool localCorrectionsPresent

Specifies whether DGPS type corrections are used.

Supported values:
  • 0 – Not used
  • 1 – Used
bool networkCorrectionsPresent

Specifies whether RTK type corrections are used.

Supported values:
  • 0 – Not used
  • 1 – Used
struct v2x_gnss_fix_rates_supported_list_t

Defines supported GNSS fix generation rates (such as 1 Hz, 5 Hz, 10 Hz).

Data Fields
uint32_t qty_rates_supported

Specify whether the listing or discovery of the supported rates is supported.

Supported values:
  • 0 – Not supported
  • 1 – Supported
pb_size_t rates_supported_hz_array_count

Number of supported rates.

uint32_t rates_supported_hz_array[32]

Array of data rates supported by the API.

struct v2x_init_t

Defines client initialization.

Data Fields
uint32_t log_level_mask

Log levels as defined in syslog.h.

char server_ip_addr[32]

IP address of the server.

struct v2x_kinematics_capabilities_t_feature_flags_t

Defines Kinematics features supported by the hardware.

Data Fields
bool has_3_axis_gyro

Specifies whether the hardware supports 3-axis gyro.

Supported values:
  • 0 – Not supported
  • 1 – Supported
bool has_3_axis_accelerometer

Specifies whether the hardware supports the 3-axis accelerometer.

Supported values:
  • 0 – Not supported
  • 1 – Supported
bool has_imu_supplemented_dead_reckoning

Specifies whether a dead reckoning (DR) solution is available and enabled or only GNSS is the result.

Supported values:
  • 0 – GNSS is available
  • 1 – DR is available
bool has_yaw_rate_sensor

Specifies whether the IMU includes a yaw rate sensor.

Supported values:
  • 0 – Does not include sensor
  • 1 – Includes sensor
bool used_vehicle_speed

Specifies whether the DR algorithm uses the vehicle speed sensor.

Supported values:
  • 0 – Does not use sensor
  • 1 – Uses sensor
bool used_single_wheel_ticks

Specifies whether the DR algorithm uses the single wheel ticks.

Supported values:
  • 0 – Does not use ticks
  • 1 – Uses ticks
bool used_front_differential_wheel_ticks

Specifies whether the DR algorithm uses two front differential wheel ticks.

Supported values:
  • 0 – Does not use ticks
  • 1 – Uses ticks
bool used_rear_differential_wheel_ticks

Specifies whether the DR algorithm uses two rear differential wheel ticks.

Supported values:
  • 0 – Does not use ticks
  • 1 – Uses ticks
bool used_vehicle_dynamic_model

Specifies whether the DR algorithm uses vehicle dynamic model factoring in differential ticks, steering, and so on.

Supported values:
  • 0 – Does not use factoring
  • 1 – Uses factoring
struct v2x_rates_t

Defines the rate type.

Data Fields
uint32_t rate_report_hz

Requested or reported current number of fixes per second.

uint32_t offset_nanoseconds

Currently unsupported.

struct v2x_kinematics_capabilities_t

Returned via v2x_kinematics_get_capabilities() for the client to discover the lower level function that this system supports.

Data Fields
v2x_kinematics_capabilities_t_feature_flags_t feature_flags

Features supported by the API.

uint32_t max_fix_rate_supported_hz

Highest rate platform that supports GNSS fix generation (in Hz).

v2x_gnss_fix_rates_supported_list_t rates_list

Supported fix rates.

struct v2x_location_fix_t

Contains a standardized set of parameters that are used for ITS applications.

The contents of this structure do not include every possible GNSS element (for example, raw range data is not included). These fields are via low latency for safety applications, both to use locally and to load into a J2945/1 or ETSI G5 EN302.637-2 CAM. For example, the fields are used for CAM-type and BSM-type safety beacons.

This structure is populated for each location or dead-reckoning fix, and it is supplied on the fix available callback.

Predefined J2735s can be used to communicate raw SV observations and RTK correction data. Currently, however, they are not supplied from this structure.

Data Fields
double utc_fix_time

UTC time in seconds.

v2x_fix_mode_t fix_mode

Location engine used to produce this record.

Supported values:

No fix, 2D, 3D, RTCM

double latitude

Latitude in degrees.

double longitude

Longitude in degrees.

double altitude

Altitude in meters above the geoid (mean sea level).

uint32_t qty_SV_in_view

Number of usable space vehicles (SV) that should be in view.

uint32_t qty_SV_used

Actual number of SVs used in this fix calculation.

v2x_GNSSstatus_t gnss_status

Status of the GNSS data.

bool has_SemiMajorAxisAccuracy

Specifies whether the value of the SemiMajorAxisAccuracy field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double SemiMajorAxisAccuracy

Accuracy of the major axis, in meters.

bool has_SemiMinorAxisAccuracy

Specifies whether the value of the SemiMinorAxisAccuracy field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double SemiMinorAxisAccuracy

Accuracy of the minor axis, in meters.

bool has_SemiMajorAxisOrientation

Specifies whether the value of the SemiMajorAxisOrientation field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double SemiMajorAxisOrientation

Orientation of the major axis, in meters.

bool has_heading

Specifies whether the value of the heading field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double heading

Track degrees relative to true north.

bool has_velocity

Specifies whether the value of the velocity field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double velocity

Speed over ground in meters/second.

bool has_climb

Specifies whether the value of the climb field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double climb

Vertical speed in meters/second.

bool has_lateral_acceleration

Specifies whether the value of the lateral_acceleration field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double lateral_acceleration

Acceleration in a latitudinal direction, in meters/second^2.

bool has_longitudinal_acceleration

Specifies whether the value of the longitudinal acceleration field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double longitudinal_acceleration

Acceleration in a longitudinal direction, in meters/second^2.

bool has_vehicle_vertical_acceleration

Specifies whether the value of the vehicle_vertical_acceleration field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double vehicle_vertical_acceleration

Vertical acceleration of the vehicle in G force.

bool has_yaw_rate_degrees_per_second

Specifies whether the value of the yaw_rate_degrees_per_second field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double yaw_rate_degrees_per_second

Yaw rate in degrees/second, per SAE J2735.

bool has_yaw_rate_95pct_confidence

Specifies whether the value of the yaw_rate_95pct_confidence field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double yaw_rate_95pct_confidence

95% confidence (2 sigma) on the yaw rate in degrees/second.

bool has_lane_position_number

Specifies whether the value of the lane_position_number field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double lane_position_number

Current lane number, where 0 is either the outer-most edge of the hard shoulder or off-road.

bool has_lane_position_95pct_confidence

Specifies whether the value of the lane_position_95pct_confidence field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
double lane_position_95pct_confidence

95% confidence range on the lane position.

bool has_time_confidence

Specifies whether the value of the time_confidence field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
float time_confidence

95% (2 sigma) confidence in number of seconds.

bool has_heading_confidence

Specifies whether the value of the heading_confidence field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
float heading_confidence

95% heading confidence in degrees.

bool has_velocity_confidence

Specifies whether the value of the velocity_confidence field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
float velocity_confidence

95% velocity confidence in meters/second.

bool has_elevation_confidence

Specifies whether the value of the elevation_confidence field is valid.

Supported values:
  • 0 – Not valid
  • 1 – Valid
float elevation_confidence

95% uncertainty range (2 sigma) confidence in meters.

uint32_t leap_seconds

Indicates that both UTC and GPS are required because IEEE 1609.2 security requires operations to be performed in raw GPS time.

Macro Definition Documentation

#define V2X_KINEMATICS_HANDLE_BAD   (-1)

Invalid handle returned by v2x_kinematics_init() upon an error.

Typedef Documentation

Kinematics data handle to the interface.

typedef void(* v2x_kinematics_init_callback_t) (v2x_status_enum_type status, void *context)

User-defined callback function called upon completion of a v2x_kinematics_init() operation.

Associated data types
v2x_status_enum_type
Parameters
[in]statusStatus of the v2x_kinematics_init() call.
[in]contextPointer to the application context from which v2x_kinematics_init() was called.
typedef void(* v2x_kinematics_rate_notification_listener_t) (v2x_status_enum_type status, v2x_rates_t *rate, void *ctx)

User-defined listener function called when a data rate is updated.

Associated data types
v2x_status_enum_type
v2x_rates_t
Parameters
[in]statusStatus of the rate change request.
[in]ratePointer to the rate.
[in]ctxPointer to the application context from which this listener was registered.
typedef void(* v2x_kinematics_set_rate_callback_t) (v2x_status_enum_type status, void *context)

User-defined callback function called upon completion of a v2x_kinematics_set_rate() operation.

Associated data types
v2x_status_enum_type
Parameters
[in]statusStatus of the v2x_kinematics_set_rate() call.
[in]contextPointer to the application context from which v2x_kinematics_set_rate() was called.
typedef void(* v2x_kinematics_get_capability_callback_t) (v2x_kinematics_capabilities_t *cap, void *context)

User-defined callback function called upon completion of a v2x_kinematics_get_capabilities() operation.

Associated data types
v2x_kinematics_capabilities_t
Parameters
[in]capPointer to the capabilities supported by the API.
[in]contextPointer to the application context from which v2x_kinematics_get_capabilities() was called.
typedef void(* v2x_kinematics_newfix_listener_t) (v2x_location_fix_t *new_fix, void *context)

User-defined listener function for kinematics data.

Associated data types
v2x_location_fix_t
Parameters
[in]new_fixPointer to the data.
[in]contextPointer to the application context from which this listener was registered.
typedef void(* v2x_kinematics_deregister_callback_t) (v2x_status_enum_type status, void *context)

User-defined callback function called upon completion of a v2x_kinematics_deregister_listener() operation.

Associated data types
v2x_status_enum_type
Parameters
[in]statusStatus of the v2x_kinematics_deregister_listener() call.
[in]contextPointer to the application context from which v2x_kinematics_deregister_listener() was called.
typedef void(* v2x_kinematics_final_callback_t) (v2x_status_enum_type status, void *context)

User-defined callback function called upon completion of a v2x_kinematics_final() operation.

Associated data types
v2x_status_enum_type
Parameters
[in]statusStatus of the v2x_kinematics_final() call.
[in]contextPointer to the application context from which v2x_kinematics_final() was called.

Enumeration Type Documentation

Valid GNSS fix modes.

Enumerator
V2X_GNSS_MODE_NOT_SEEN 

SV is unavailable or not in view.

V2X_GNSS_MODE_NO_FIX 

No SV fix.

V2X_GNSS_MODE_2D 

2D fix with latitude and longitude information.

V2X_GNSS_MODE_3D 

3D fix with latitude, longitude, and altitude information.

Function Documentation

v2x_api_ver_t v2x_kinematics_api_version ( void  )

Gets the compiled API version interface (as an integer number).

Returns
v2x_api_ver_t – Filled with the version number, build date, and detailed build information.
v2x_kinematics_handle_t v2x_kinematics_init ( v2x_init_t param,
v2x_kinematics_init_callback_t  cb,
void *  context 
)

Initializes the Kinematics library.

Associated data types
v2x_init_t
v2x_kinematics_init_callback_t
Parameters
[in]paramPointer to the structure that contains parameters for the IP address of the server, logging level, and so on.
[in]cbCallback function called when initialization is complete.
[in]contextPointer to the application context for use with the callbacks, which can help the caller code.
Returns
Handle number to use with subsequent calls.
V2X_KINEMATICS_HANDLE_BAD – Upon an error.
v2x_status_enum_type v2x_kinematics_start_rate_notification ( v2x_kinematics_handle_t  handle,
v2x_kinematics_rate_notification_listener_t  cb,
void *  context 
)

Gets the current rate and offset from the Kinematics library.

Associated data types
v2x_kinematics_handle_t
v2x_kinematics_rate_notification_listener_t
Parameters
[in]handleHandle number to use with subsequent calls. If there is an error in initialization, the value is -1.
[in]cbCallback function used to report rate notification changes.
[in]contextPointer to the application context for use with the callbacks, which can help the caller code.
Returns
Indication of success or failure from v2x_status_enum_type.
v2x_status_enum_type v2x_kinematics_set_rate ( v2x_kinematics_handle_t  handle,
v2x_rates_t rate,
v2x_kinematics_set_rate_callback_t  cb,
void *  context 
)

Sets the current rate and offset from the Kinematics library.

Associated data types
v2x_kinematics_handle_t
v2x_rates_t
v2x_kinematics_set_rate_callback_t
Parameters
[in]handleHandle number to use with subsequent calls. If there is an error in initialization, the value is -1.
[in]ratePointer to the rate structure filled with the fix timing parameters.
[in]cbCallback function called when rates and offsets are successfully set. This parameter can be NULL.
[in]contextPointer to the application context for use with the callbacks, which can help the caller code.
Returns
Indication of success or failure from v2x_status_enum_type.
v2x_status_enum_type v2x_kinematics_register_listener ( v2x_kinematics_handle_t  handle,
v2x_kinematics_newfix_listener_t  listener,
void *  context 
)

Registers for a Kinematics result listener callback at the requested rate.

Associated data types
v2x_kinematics_handle_t
v2x_kinematics_newfix_listener_t
Parameters
[in]handleHandle number to use with subsequent calls. If there is an error in initialization, the value is -1.
[in]listenerCallback function to use for this listener.
[in]contextPointer to the application context for use with the callbacks, which can help the caller code.
Detailed description
This function requests GNSS fix/motion callbacks at a specified rate (Hz) with a specified offset.
Only certain rates are supported (such as 1 Hz, 2 Hz, 5 Hz, 10 Hz), which are obtained from v2x_kinematics_get_capabilities().
Currently, a request cannot be made for a rate slower than 1 Hz.
Returns
Indication of success or failure from v2x_status_enum_type.
v2x_status_enum_type v2x_kinematics_deregister_listener ( v2x_kinematics_handle_t  handle,
v2x_kinematics_deregister_callback_t  cb,
void *  context 
)

Deregisters a previously registered GNSS fix that the listener established earlier via v2x_kinematics_register_listener().

Associated data types
v2x_kinematics_handle_t
v2x_kinematics_deregister_callback_t
Parameters
[in]handleHandle number of the registered fix.
[in]cbCallback function to use for this listener. This parameter can be NULL.
[in]contextPointer to the application context for use with the callbacks, which can help the caller code.
Returns
Indication of success or failure from v2x_status_enum_type.
v2x_status_enum_type v2x_kinematics_final ( v2x_kinematics_handle_t  handle,
v2x_kinematics_final_callback_t  cb,
void *  context 
)

Terminates the Kinematics library.

Associated data types
v2x_kinematics_handle_t
v2x_kinematics_final_callback_t
Parameters
[in]handleHandle number of the library.
[in]cbCallback function called when termination is complete. This parameter can be NULL.
[in]contextPointer to the application context for use with the callbacks, which can help the caller code.
Returns
Indication of success or failure from v2x_status_enum_type.
void v2x_kinematics_enable_fixes ( v2x_kinematics_handle_t  handle)

Enables the Kinematics fixes from GNSS.

Associated data types
v2x_kinematics_handle_t
Parameters
[in]handleUnique identifier for the library.
Returns
None.
void v2x_kinematics_disable_fixes ( v2x_kinematics_handle_t  handle)

Disables the Kinematics fixes from GNSS.

Associated data types
v2x_kinematics_handle_t
Parameters
[in]handleUnique identifier for the library.
Returns
None.