GPS Library API

Commands

GPS library exposes two commands to interact with GPS hardware from console.

  1. GPSINFO

    This command is to get GPS information. This command responds with Following information:

    Status: active or inactive status of gps hardware
    Time: parsed Time information from NMEA
    Date: parsed Date information from NMEA
    Fix: GPS fix status, ‘A’ or ‘V’
    Sat: Number of visible satellites
    Speed: Current speed, This is filtered data parameter after processing
    Dir: Heading value (filtered)
    PDOP: Current PDOP value
    HDOP: Current HDOP value
    Lat: Latitude value in degree (filtered)
    Long: Longitude value in degree (filtered)
    Alt: Altitude data (filtered)
    ODO: Odometer in meters (calculated)

    To see the above parameters unfiltered, send “raw” argument to GPSINFO command, e.g.:

    gpsinfo=raw

  2. GPSCMD

    Send command to GPS hardware.

    Usage Format:

    gpscmd=arg

    Arg can be following:

    1. COLDSTART: send cold start command to GPS hardware.

    2. HOTSTART: send hot start command to GPS hardware.

    3. WARMSTART: send warm start command to GPS hardware.

    It is also possible to send raw command to device in place of argument, e.g.:

    gpscmd="PMTK353,1,1,1,0,0"

    Please make sure to put raw command inside quotes. There is no need to add $ or checksum, it will be added based on selected driver.

Header File

Source: include/gpslib.h

#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 harshbrake

Harsh braking 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_HARSHBRAKE

Default harsh braking/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_HARSHBRAKE

Harsh brake 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_HARSHBRAKE_LIMIT

Set threshold for Harsh braking 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, expects parameter as double

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