Tel: +353 87 988 1568

Web: http://www.hillstone-software.com
Email: [email protected]
36 Wheatfield Grove, Clondalkin, Dublin 22, Ireland

HsGpsDll Library User Manual (v1.1)

Date: 11/03/2008

HsGpsDll Library User Manual (v1.1)....................................................................................................................... 1

Date: 10/03/2008.................................................................................................................................................... 1
1 Introduction ......................................................................................................................................................... 2
1.1 About HsGpsDll............................................................................................................................................ 2
1.1.1 Overview .............................................................................................................................................. 2
1.1.2 What components are included in HsGpsDll .................................................................................... 2
1.1.3 Limitations in Evaluation Version ....................................................................................................... 2
1.1.4 HsGpsDll Internal Architecture........................................................................................................... 3
1.1.5 Purchasing Information....................................................................................................................... 3
2 HsGpsDll API Specification ............................................................................................................................... 4
2.1 Function Reference...................................................................................................................................... 4
2.1.1 HsGPSDllOpen ................................................................................................................................... 4
2.1.2 HsGPSDllClose ................................................................................................................................... 5
2.1.3 HsGPSDLLGetPosition....................................................................................................................... 5
2.1.4 HsGPSDLLGetPositionDegrees ........................................................................................................ 7
2.1.5 HsGPSDLLGetAltitude ....................................................................................................................... 8
2.1.6 HsGPSDLLGetSpeed ......................................................................................................................... 9
2.2 Error Codes and Other Constants .............................................................................................................. 9
2.2.1 HsGpsDll return codes........................................................................................................................ 9
2.2.2 Other Constants .................................................................................................................................. 9
1 Introduction
1.1 About HsGpsDll
1.1.1 Overview
HsGpsDll is a Windows Dynamic Link Library which provides access to any NMEA-183 compliant GPS
receiver via a serial communications port.

HsGpsDll is designed for use from Visual C, Visual Basic or other programming languages, capable of calling
DLL functions.

HsGpsDll allows a user application to read from a connected GPS device:

· current GPS geographical position fix (latitude and longitude) in degrees, and decimal seconds
(for example 53’ 20.6107” N, 6’ 23.4648” W)
· current GPS geographical position fix (latitude and longitude) in decimal degree format
(for example 53.343513 N, 6.391080 W)
· current speed (velocity over ground)
· number of satellites in view
· fix quality (valid or not)
· current altitude (against mean sea level)
· UTC date and time

To obtain the above information, HsGpsDll decodes the following sentences of NMEA-183 (National Marine
Electronics Association, Interface Standard 0183:
· $GPGGA - geographical position fix data
· $GPRMC – minimum recommended fix data
· $GPVTG - velocity over ground

1.1.2 What components are included in HsGpsDll

HsGpsDll Standard Edition:

· HsGpsDll.dll - Windows DLL (Dynamic Link Library) for use from programs in Visual C, Visual Basic
or other languages
· HsGpsDemoVC - Visual C test application with source code using HsGpsDll.dll
· HsGpsDemoVB6 - Visual Basic test application with source code using HsGpsDll.dll

HsGpsDll Blueprint Edition:

Includes everything in Standard edition plus FULL SOURCE CODE in Visual C (plain C style), including core
GPS NMEA message processing engine.

1.1.3 Limitations in Evaluation Version

There are several limitations in the evaluation version of HsGpsDll library, which are removed from the full
version:
· Every time evaluation version of HsGpsDll library is loaded it displays a reminder message (nag
screen), which requires a user to click Okay to continue.
· Evaluation version has a built it use count. After the use count is exceeded (the GPS position or
speed retrieved several times), the library will fail every call and will return the corresponding error
code (HS_GPSDLL_RC_EVAL_EXCEEDED= 0x06). The application will need to exit and restart to
reset the use count.
· No source code is supplied with free evaluation version. The full source code is supplied with full
version of HsGpsDll Blueprint Edition.
1.1.4 HsGpsDll Internal Architecture

Visual C, C# or VB
Applications

Supplied to customers

HsGpsDll.Dll HsGpsDemoVC
API Layer (Visual C Demo
Application)

HsGps.Lib HsGpsDemoVB6
(Static C library) (Visual Basic Demo
Core GPS / NMEA Application)
Decoding module

HsCom.Lib
(Static C Library)
Serial
Communications
Module

1.1.5 Purchasing Information

To purchase HsGpsDll library and for pricing information, please visit
http://www.hillstone-software.com/hs_gpsdll_buy.htm

Alternatively contact us:

Hillstone Software,
http://www.hillstone-software.com
mailto:[email protected]
Tel. +353 87 988 1568
2 HsGpsDll API Specification
2.1 Function Reference

2.1.1 HsGPSDllOpen
Declaration:
extern long HS_GPSDLL_API HsGPSDllOpen(
long portno,
long baudrate, // baud rate 110 to 115200
long databits, // number of data bits
long parity, // parity
long stopbits, // number of stop bits
long options,
long *rc
)

Summary:
Opens a GPS port and associated serial communications port and starts receiving NMEA data from a GPS
receiver. Call this function before calling other functions to get current GPS information.

Parameters:
portno
Serial communications port number from 0 to 31 to which a GPS receiver is connected. 0=COM1,
1=COM2…31=COM32

baudrate
COM port speed, the following values are valid speeds: 110, 300, 600, 1200, 2400, 4800, 9600,
14400, 19200, 38400, 56000, 57600, 115200, 128000, 256000. Most GPS receivers operate at 4800 baud,
however some receivers may operate at a different fixed or configurable rate.

databits
COM port data size in number of bits. Valid values are 5,6,7,8

parity
COM port parity code as follows: 2=EVEN, 3=MARK ,0=NONE, 1=ODD, 4=SPACE

stopbits
COM port stop bits code as follows: 0=0, 1=1.5, 2=2

options
Operating options: USE_GPGAA = position coordinates will be obtained by HsGpsDll from $GPGGA
NMEA sentence; USE_GPRMC = position coordinates will be obtained by HsGpsDll from $GPRMC NMEA
sentence

rc
Pointer to long variable to receive function return code (See “Return values” below)

Return values:

HS_GPSDLL_RC_ALREADY_INIT GPS library is already initialised

HS_GPSDLL_RC_FAIL Failed to open serial communications port
HS_GPSDLL_RC_OK Success, GPS port is open
2.1.2 HsGPSDllClose
Declaration:
extern long HS_GPSDLL_API HsGPSDllClose(long *rc);

Summary:
Closes HsGpsDll library interface and the serial port to which the GPS receiver is connected.

Parameters:

rc
Pointer to long variable to receive function return code (See “Return values” below)

Return values:

HS_GPSDLL_RC_NOT_INIT GPS library not initialised

HS_GPSDLL_RC_FAIL Failed to close serial communications port
HS_GPSDLL_RC_OK Success, GPS port is closed

2.1.3 HsGPSDLLGetPosition
Declaration:
extern long HS_GPSDLL_API HsGPSDLLGetPosition(
long *lat_deg, /* latitude degrees */
long *lat_min, /* latitude minutes */
long *lat_dec, /* latitude decimal part of minutes */
long *lat_dir, /* latitude 0 –North, 1 -South */

long *lon_deg, /* longitude degrees */

long *lon_min, /* longitude minutes */
long *lon_dec, /* longitude decimal part of minutes */
long *lon_dir, /* longitude 2 -East 3 -West */

long *fix_valid, /* 1 - fix valid, 0 - fix not valid (As received from GPS device) */
long *nsat, /* Number of sattelites used in position fix */

long *utc_hour, /* UTC hour */

long *utc_min, /* UTC minute */
long *utc_sec, /* UTC second */
long *utc_msec, /* UTC millisecond */

long *day, /* day of fix */

long *month, /* month of fix */
long *year, /* year of fix */

long *rc /* result return code */

);

Summary:
This function returns last known:
· Geographical position coordinates (latitude and longitude) in degrees and decimal minutes
· Fix quality (valid or not valid)
· Number of satellites in view
· UTC date and time
The latitude and longitude coordinates are returned in the form of integer degrees, integer part of minutes,
decimal part of minutes (returned in an integer) and direction code of latitude and longitude.

Example reading:
lat_deg = 53 lat_min = 20 lat_dec = 6107 lat_dir = 0 à 53’ 20.6107” North
lon_deg = 6 lon_min = 23 lon_dec = 4638 lon_dir = 3 à 6’ 23.4638” West

GPS receiver normally outputs NMEA messages containing current position data once per second. You can
call this function based on a timer event or callback to continuously obtain last known GPS data.

Parameters:

lat_deg
Pointer to long variable which receives latitude degrees

lat_min
Pointer to long variable which receives latitude minutes (integer part)

lat_dec
Pointer to long variable which receives latitude minutes (decimal part)

lat_dir
Pointer to long variable which receives latitude direction code: 0 –North, 1 -South

lon_deg
Pointer to long variable which receives longitude degrees

lon_min
Pointer to long variable which receives longitude minutes (integer part)

lon_dec
Pointer to long variable which receives longitude minutes (decimal part)

lon_dir
Pointer to long variable which receives longitude direction code: 2 –East, 3 -West

utc_hour
Pointer to long variable which receives UTC hour

utc_min
Pointer to long variable which receives UTC minute

utc_sec
Pointer to long variable which receives UTC second

utc_msec
Pointer to long variable which receives UTC millisecond

day
Pointer to long variable which receives day of current date

month
Pointer to long variable which receives month of current date

year
Pointer to long variable which receives year of current date
rc
Pointer to long variable to receive function return code (See “Return values” below)

Return values:

HS_GPSDLL_RC_NOT_INIT GPS library not initialised

HS_GPSDLL_RC_INV_PAR Invalid parameters
HS_GPSDLL_RC_EVAL_EXCEEDED Evaluation version only. Usage count exceeded. You
must restart your application to continue evaluation
(this unloads and re-loads HsGpsDll into memory.
HS_GPSDLL_RC_NOT_AVAIL GPS data not yet available
HS_GPSDLL_RC_OK Success

2.1.4 HsGPSDLLGetPositionDegrees
Declaration:
extern long HS_GPSDLL_API HsGPSDLLGetPositionDegrees(
float *latidude, // returns latitude in decimal degrees
float *longitude, // returns longitude in decimal degrees
char *lat_direction, // 'N' or 'S' (north, south)
char *lon_direction, // 'E' or 'W' (east, west)
long *rc /* result return code */
);

Summary:
This function returns last known geographical position coordinates in decimal degree format, for example:

53'20.6096"N = 53.343493 N
6'23.4618"W = 6.39103 W

GPS receiver normally outputs NMEA messages containing current position data once per second. You can
call this function based on a timer event or callback to continuously obtain last known GPS data.

Parameters:

latitude
Pointer to a variable of type float that receives latitude coordinate of current position in decimal
degree format

longitude
Pointer to a variable of type float that receives longitude coordinate of current position in decimal
degree format

lat_direction
Pointer to char variable to receive direction of latidude, ‘N’ or ‘S’ for North or South

lon_direction
Pointer to char variable to receive direction of longitude, ‘E’ or ‘W’ for East or West

rc
Pointer to long variable to receive function return code (See “Return values” below)
Return values:

HS_GPSDLL_RC_NOT_INIT GPS library not initialised

HS_GPSDLL_RC_INV_PAR Invalid parameters
HS_GPSDLL_RC_EVAL_EXCEEDED Evaluation version only. Usage count exceeded. You
must restart your application to continue evaluation
(this unloads and re-loads HsGpsDll into memory.
HS_GPSDLL_RC_NOT_AVAIL GPS data not yet available
HS_GPSDLL_RC_OK Success

2.1.5 HsGPSDLLGetAltitude
Declaration:

extern long HS_GPSDLL_API HsGPSDLLGetAltitude(

float *altitude, /* altitude mean sea level in meters */
char *unit_of_altitude, /* unit of altitude (e.g. 'M' meters) */
long *rc /* result return code */
);

Summary:
This function returns last known altitude (mean sea level)

GPS receiver normally outputs NMEA messages containing current position data once per second. You can
call this function based on a timer event or callback to continuously obtain last known GPS data.

Parameters:

altitude
Pointer to float variable which receives altitude measured against mean sea level

unit_of_altidude
Pointer to character to receive measurement unit of antidote. ‘M’ for meters.

rc
Pointer to long variable to receive function return code (See “Return values” below)

Return values:

HS_GPSDLL_RC_NOT_INIT GPS library not initialised

HS_GPSDLL_RC_INV_PAR Invalid parameters
HS_GPSDLL_RC_EVAL_EXCEEDED Evaluation version only. Usage count exceeded. You
must restart your application to continue evaluation
(this unloads and re-loads HsGpsDll into memory.
HS_GPSDLL_RC_NOT_AVAIL GPS data not yet available
HS_GPSDLL_RC_OK Success
2.1.6 HsGPSDLLGetSpeed
Declaration:

extern long HS_GPSDLL_API HsGPSDLLGetSpeed(long *speed_kph, long *rc);

Summary:
This function returns last known speed in kilometres per hour

GPS receiver normally outputs NMEA messages containing current position data once per second. You can
call this function based on a timer event or callback to continuously obtain last known GPS data.

Parameters:

speed_kph
Pointer to long variable to receive current last known speed in kilometres per hour.

rc
Pointer to long variable to receive function return code (See “Return values” below)

Return values:

HS_GPSDLL_RC_NOT_INIT GPS library not initialised

HS_GPSDLL_RC_INV_PAR Invalid parameters
HS_GPSDLL_RC_EVAL_EXCEEDED Evaluation version only. Usage count exceeded. You
must restart your application to continue evaluation
(this unloads and re-loads HsGpsDll into memory.
HS_GPSDLL_RC_NOT_AVAIL GPS data not yet available
HS_GPSDLL_RC_OK Success

2.2 Error Codes and Other Constants

2.2.1 HsGpsDll return codes

Name Value Comment

HS_GPSDLL_RC_OK 0 Success
HS_GPSDLL_RC_ALREADY_INIT 1 Library already initialised
HS_GPSDLL_RC_FAIL 2 Failure
HS_GPSDLL_RC_NOT_INIT 3 Library not initialised
HS_GPSDLL_RC_NOT_AVAIL 4 GPS data not available
HS_GPSDLL_RC_INV_PAR 5 Invalid parameters
HS_GPSDLL_RC_EVAL_EXCEEDED 6 Evaluation version only. Usage count exceeded. You
must restart your application to continue evaluation (this
unloads and re-loads HsGpsDll into memory.

2.2.2 Other Constants

Name Value Comment

USE_GPGAA 1 Extract coordinates from $GPGAA message
USE_GPRMC 2 Extract coordinates from $GP RMC message