GPS Library

MT2503 SoC has on-chip GNSS module supports GPS + GLONASS, Galileo, Beidou constellations. Logicrom gps library does all the heavy lifting and make it easy to use the full capabilities of GNSS module. Some features of gps library are:

  • Most accurate software odometer

  • Motion detection based on GPS data

  • No position drift after vehicle stops

  • Critical events based on user configuration:

    1. Harsh Acceleration

    2. Harsh Breaking

    3. Harsh turning/cornering

    4. Over speed

  • Vehicle turn notification

  • GPS status notification

API Reference

Header File

Functions

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

Initialize GPS library and start GPS data handler task

Return

0 on success, negative value on failure

Parameters

  • port: [in] device file where GPS is connected, e.g. /dev/ttyS1

  • config: [in] GPS initial configuration, see gpsconfig_t

int gps_sendcmd(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()
Return

0 on success, negative value on failure

Parameters

  • cmd: [in] GPS command without $ and CRC

void gpslib_reconfig(int type)

Reconfigure GPS module. This function may be called if application performs a hardware or software reset to GPS module.

Parameters

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.

Return

0 on success, -1 no more point available in trace.

Parameters

  • gps: [out] GPS data structure to fill

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

Return

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

int gps_uart_write(unsigned char *buf, int len)

Write data on GPS port

Return

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

Parameters

  • buf: [in] Buffer with data to send

  • len: [in] Length of data in buf

time_t gpsmktime(char *date_in, char *time_in)

Convert GPS string date time to seconds since Epoch.

Return

Time value in seconds since Epoch

Parameters

  • date_in: [in] GPS date in ddmmyy format

  • time_in: [in] GPS Time in hhmmss format

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

Check if point is within geofence or not

Return

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

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

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 type

GPS type gpstype_e, For MT2503 GPS use GPS_TYPE_MTK

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

Parameters

void (*gps_datacallback)(struct gpsdata_t*)

GPS parsed data callback

Parameters

  • GPS: Data structure pointer

void (*gps_nmea_cb)(const char *nmea)

GPS Raw data callback

Parameters

  • nmea: NMEA data string

Enumerations

enum gpstype_e

GPS Module type

Values:

enumerator GPS_TYPE_ANY

GPS module that is not known to library

enumerator GPS_TYPE_SIRF

SIRF Star III GPS module

enumerator GPS_TYPE_MTK

GPS/GNSS module based on Mediatek chipset

enumerator GPS_TYPE_MTKIRNSS

IRNSS Module from MTK

enumerator GPS_TYPE_STIRNSS

GNSS module with IRNSS support based on STA80xx chipset (e.g. L89)

enumerator GPS_TYPE_UNICORE

Default value for BC20 as onboard GNSS module

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