GPS Library API¶

Header File¶

#include <gpslib.h>

Functions¶

int gpslib_init(char *port, struct gpsconfig_t *config)¶

Initialize GPS library and start GPS data handler task

It is recommended to set GPS driver before calling this function.

Parameters

port – [in] device file where GPS is connected, e.g. /dev/ttyS1
config – [in] GPS initial configuration, see gpsconfig_t

Returns

0 on success, negative value on failure

int gps_send_command(const char *cmd)¶

Send command to GPS. GPS commands format:

$[command]*[checksum][cr][lf]

This function expect “command” as cmd parameter. The header, footer and crc value will be calculated internally based on GPS type configured during gps initialization see gpslib_init()

Parameters: cmd – [in] GPS command without $ and CRC
Returns: 0 on success, negative value on failure

void gpslib_reconfig(void)¶: Reconfigure GPS module. This function may be called if application performs a hardware or software reset to GPS module.

void gps_getdata(struct gpsdata_t *gps)¶

Get current GPS data structure

Parameters: gps – [out] GPS structure to fill

int gps_get_starttrace(struct gpsdata_t *gps)¶

Get movement trace from starting position. This function can be called after GPS_EVENT_MOTION_START event has occurred.

GPS library has complex logic to detect movement based on GPS data, which may cause delay in firing motion start event. However GPS library keep track of movement made from the start position to the moment when GPS event is generated. So by calling this function the complete movement trace can be sent to server without missing any point from track.

Parameters: gps – [out] GPS data structure to fill
Returns: 0 on success, -1 no more point available in trace.

void gps_set_param(int type, void *val)¶

Set GPS parameter

Parameters

type – [in] GPS parameter type, see gpsparam_e
val – [out] Pointer to GPS parameter value to set

void gps_get_param(int type, void *val)¶

Get GPS parameter

Parameters

type – [in] GPS parameter type, see gpsparam_e
val – [out] GPS parameter value buffer filled on return

int gps_getstatus(void)¶

Get GPS status

Returns: Returns 0 if GPS is inactive or not responding Returns 1 if GPS is active and running fine.

int gps_uart_write(const void *buf, int len)¶

Write data on GPS port

Parameters

buf – [in] Buffer with data to send
len – [in] Length of data in buf

Returns

On success, returns actual number of bytes written or -1 on failure errno will be set on failure.

time_t gpsmktime(char *date_in, char *time_in)¶

Convert GPS string date time to seconds since Epoch.

Parameters

date_in – [in] GPS date in ddmmyy format
time_in – [in] GPS Time in hhmmss format

Returns

Time value in seconds since Epoch

int geofence_check(int type, const struct point_t *fence, unsigned int corners_radius, const struct point_t *point)¶

Check if point is within geofence or not

Parameters

type – [in] Geofence type, see geofence_type_e
fence – [in] For polygon type fence, Array of GPS points For Circular fence, pointer to point representing center of circle
corners_radius – [in] For polygon fence, Number of corners in the fence For circular fence, radius of fence in meters
point – [in] Input Point/GPS coordinates to test

Returns

Returns True (1) if point is inside the geofence False (0) if point is outside geofence -22 if parameters are invalid.

int gps_motionassist_config(int type)¶

Add motion detect assistance to GPS algorithm.

Parameters: type – Motion detect type gpsmatype_t
Returns: return 0 on success

int gps_motionassist(int event)¶

Inform GPS algorithm about event generated from assistance source set using gps_motionassist_config()

Parameters: event – Motion detect event gpsmaevent_t
Returns: return 0 on success

Structures¶

struct point_t¶

GPS point structure

Public Members

double lat¶: Latitude in degrees

double lng¶: Longitude in degrees

struct gpsdata_t¶

GPS data structure

Public Members

char time[7]¶: GPS UTC time as hhmmss

char date[7]¶: GPS UTC date as ddmmyy

char fix¶: GPS Fix status ‘A’ or ‘V’

int satinview¶: Satellites in view and used in current fix

float speedkmph¶: GPS Speed in Km/h

float direction¶: Direction/Course over ground in degrees

double lat¶: Latitude in degree

double lng¶: Longitude in degree

float altitude¶: Altitude value in meters

double odom¶: Odometer value in meteres

float pdop¶: HDOP and PDOP values

struct gpsconfig_t¶

GPS Initial configuration structure

Public Members

int baud¶: GPS Baudrate

float speedlimit¶: Over-speed limit in Km/h

float harshturn¶: Harsh Turning speed limit in Km/h

float harshbrk¶: Harsh breaking limit in g (m/s2)

float overaccel¶: Harsh acceleration limit in g (m/s2)

void (*gps_event_cb)(int)¶

GPS event callback function

Param GPS: Event see gpsevent_e

void (*gps_datacallback)(struct gpsdata_t*)¶

GPS parsed data callback

Param GPS: Data structure pointer

void (*gps_nmea_cb)(const char *nmea)¶

GPS Raw data callback

Param nmea: NMEA data string

Macros¶

DEF_HARSHBREAK¶: Default harsh breaking/deceleration value - 0.55g.

DEF_OVERACCEL¶: Default Harsh acceleration value - 0.43g.

DEF_HARSHTURN¶: Default harsh turning speed - 30Km/h.

DEF_SPEEDLIMIT¶: Default overspeed limit - 80Km/h.

Enumerations¶

enum geofence_type_e¶

Geo-fence type

Values:

enumerator FENCE_TYPE_CIRCLE¶: Geo-fence of type circle

enumerator FENCE_TYPE_POLY¶: Geo-fence of type polygon with more than 2 points

enum gpsevent_e¶

GPS library Events

Values:

enumerator GPS_EVENT_FIRST_FIX¶: GPS first fix event after system startup

enumerator GPS_EVENT_MOTION_STOP¶: Motion stop event

enumerator GPS_EVENT_MOTION_START¶: Motion start event. use gps_get_starttrace function to get complete movement trace.

enumerator GPS_EVENT_HARSHBREAK¶: Harsh break detected

enumerator GPS_EVENT_OVERACCEL¶: Harsh/over acceleration detected

enumerator GPS_EVENT_OVERSPEED¶: Over-speed detected

enumerator GPS_EVENT_SPEED_NORMAL¶: Speed back to normal, Occurs after over-speed is detected

enumerator GPS_EVENT_COG_CHANGED¶: Course over ground change event. Occurs during turns or on curves

enumerator GPS_EVENT_HARSHTURN¶: Harsh Turning/cornering detected

enumerator GPS_EVENT_NO_RESPONSE¶: No response from GPS module

enumerator GPS_EVENT_GPS_LOST¶: GPS fix lost event

enumerator GPS_EVENT_GPS_LOCKED¶: GPS fix acquired event

enumerator GPS_EVENT_GPS_OK¶: GPS response normal, usually comes after GPS_EVENT_NO_RESPONSE event when start GPS working properly again.

enum gpsparam_e¶

GPS Configuration parameter type

Values:

enumerator GPS_PARAM_HARSHBREAK_LIMIT¶: Set threshold for Harsh breaking in g (m/s2). Expects param as float

enumerator GPS_PARAM_OVERACCEL_LIMIT¶: Set threshold for Harsh acceleration in g (m/s2). Expects param as float

enumerator GPS_PARAM_SPEEDLIMIT¶: Set over-speed limit in Km/h, expects param as float

enumerator GPS_PARAM_TURNINGSPEED_LIMIT¶: Set harsh turning speed limit in Km/h, expects parameter as float

enumerator GPS_PARAM_ODOMETER¶: Set odometer value in meters

enum gpsmatype_t¶

GPS Motion assistance type

Values:

enumerator GPS_MOTIONASSIST_TYPE_NONE¶: Motion assistance disabled

enumerator GPS_MOTIONASSIST_TYPE_IGNITION¶: Motion assistance set to ignition

enumerator GPS_MOTIONASSIST_TYPE_MOTIONSENSE¶: Motion assistance set to motion sensor

enum gpsmaevent_t¶

GPS Motion assistance event generated from assistance source

Values:

enumerator MOTIONASSIST_EVENT_IGN_ON¶: Ignition on event

enumerator MOTIONASSIST_EVENT_IGN_OFF¶: Ignition off event

enumerator MOTIONASSIST_EVENT_MOTION_DETECT¶: Motion detected event