Defines
#define	GPS_CALLBACK_ALTITUDE 19
#define	GPS_CALLBACK_COORDINATES 17
#define	GPS_CALLBACK_DATE_TIME 21
#define	GPS_CALLBACK_MOTION 20
#define	GPS_CALLBACK_STATUS 18
#define	GPS_DEVICE_IDENTIFIER 222
#define	GPS_FIX_2D_FIX 2
#define	GPS_FIX_3D_FIX 3
#define	GPS_FIX_NO_FIX 1
#define	GPS_FUNCTION_GET_ALTITUDE 3
#define	GPS_FUNCTION_GET_ALTITUDE_CALLBACK_PERIOD 12
#define	GPS_FUNCTION_GET_COORDINATES 1
#define	GPS_FUNCTION_GET_COORDINATES_CALLBACK_PERIOD 8
#define	GPS_FUNCTION_GET_DATE_TIME 5
#define	GPS_FUNCTION_GET_DATE_TIME_CALLBACK_PERIOD 16
#define	GPS_FUNCTION_GET_IDENTITY 255
#define	GPS_FUNCTION_GET_MOTION 4
#define	GPS_FUNCTION_GET_MOTION_CALLBACK_PERIOD 14
#define	GPS_FUNCTION_GET_STATUS 2
#define	GPS_FUNCTION_GET_STATUS_CALLBACK_PERIOD 10
#define	GPS_FUNCTION_RESTART 6
#define	GPS_FUNCTION_SET_ALTITUDE_CALLBACK_PERIOD 11
#define	GPS_FUNCTION_SET_COORDINATES_CALLBACK_PERIOD 7
#define	GPS_FUNCTION_SET_DATE_TIME_CALLBACK_PERIOD 15
#define	GPS_FUNCTION_SET_MOTION_CALLBACK_PERIOD 13
#define	GPS_FUNCTION_SET_STATUS_CALLBACK_PERIOD 9
#define	GPS_RESTART_TYPE_COLD_START 2
#define	GPS_RESTART_TYPE_FACTORY_RESET 3
#define	GPS_RESTART_TYPE_HOT_START 0
#define	GPS_RESTART_TYPE_WARM_START 1
Typedefs
typedef Device	GPS
Functions
void	gps_create (GPS gps, const char uid, IPConnection *ipcon)
void	gps_destroy (GPS *gps)
int	gps_get_altitude (GPS gps, uint32_t ret_altitude, uint32_t *ret_geoidal_separation)
int	gps_get_altitude_callback_period (GPS gps, uint32_t ret_period)
int	gps_get_api_version (GPS *gps, uint8_t ret_api_version[3])
int	gps_get_coordinates (GPS gps, uint32_t ret_latitude, char ret_ns, uint32_t ret_longitude, char ret_ew, uint16_t ret_pdop, uint16_t ret_hdop, uint16_t ret_vdop, uint16_t *ret_epe)
int	gps_get_coordinates_callback_period (GPS gps, uint32_t ret_period)
int	gps_get_date_time (GPS gps, uint32_t ret_date, uint32_t *ret_time)
int	gps_get_date_time_callback_period (GPS gps, uint32_t ret_period)
int	gps_get_identity (GPS gps, char ret_uid[8], char ret_connected_uid[8], char ret_position, uint8_t ret_hardware_version[3], uint8_t ret_firmware_version[3], uint16_t *ret_device_identifier)
int	gps_get_motion (GPS gps, uint32_t ret_course, uint32_t *ret_speed)
int	gps_get_motion_callback_period (GPS gps, uint32_t ret_period)
int	gps_get_response_expected (GPS gps, uint8_t function_id, bool ret_response_expected)
int	gps_get_status (GPS gps, uint8_t ret_fix, uint8_t ret_satellites_view, uint8_t ret_satellites_used)
int	gps_get_status_callback_period (GPS gps, uint32_t ret_period)
void	gps_register_callback (GPS gps, uint8_t id, void callback, void *user_data)
int	gps_restart (GPS *gps, uint8_t restart_type)
int	gps_set_altitude_callback_period (GPS *gps, uint32_t period)
int	gps_set_coordinates_callback_period (GPS *gps, uint32_t period)
int	gps_set_date_time_callback_period (GPS *gps, uint32_t period)
int	gps_set_motion_callback_period (GPS *gps, uint32_t period)
int	gps_set_response_expected (GPS *gps, uint8_t function_id, bool response_expected)
int	gps_set_response_expected_all (GPS *gps, bool response_expected)
int	gps_set_status_callback_period (GPS *gps, uint32_t period)

Define Documentation

#define GPS_CALLBACK_ALTITUDE 19

Signature:

 void callback(uint32_t altitude, uint32_t geoidal_separation, void *user_data)

This callback is triggered periodically with the period that is set by gps_set_altitude_callback_period. The parameters are the same as for gps_get_altitude.

GPS_CALLBACK_ALTITUDE is only triggered if the altitude changed since the last triggering and if there is currently a fix as indicated by gps_get_status.

Definition at line 158 of file bricklet_gps.h.

#define GPS_CALLBACK_COORDINATES 17

Signature:

 void callback(uint32_t latitude, char ns, uint32_t longitude, char ew, uint16_t pdop, uint16_t hdop, uint16_t vdop, uint16_t epe, void *user_data)

This callback is triggered periodically with the period that is set by gps_set_coordinates_callback_period. The parameters are the same as for gps_get_coordinates.

GPS_CALLBACK_COORDINATES is only triggered if the coordinates changed since the last triggering and if there is currently a fix as indicated by gps_get_status.

Definition at line 129 of file bricklet_gps.h.

#define GPS_CALLBACK_DATE_TIME 21

Signature:

 void callback(uint32_t date, uint32_t time, void *user_data)

This callback is triggered periodically with the period that is set by gps_set_date_time_callback_period. The parameters are the same as for gps_get_date_time.

GPS_CALLBACK_DATE_TIME is only triggered if the date or time changed since the last triggering.

Definition at line 187 of file bricklet_gps.h.

#define GPS_CALLBACK_MOTION 20

Signature:

 void callback(uint32_t course, uint32_t speed, void *user_data)

This callback is triggered periodically with the period that is set by gps_set_motion_callback_period. The parameters are the same as for gps_get_motion.

GPS_CALLBACK_MOTION is only triggered if the motion changed since the last triggering and if there is currently a fix as indicated by gps_get_status.

Definition at line 173 of file bricklet_gps.h.

#define GPS_CALLBACK_STATUS 18

Signature:

 void callback(uint8_t fix, uint8_t satellites_view, uint8_t satellites_used, void *user_data)

This callback is triggered periodically with the period that is set by gps_set_status_callback_period. The parameters are the same as for gps_get_status.

GPS_CALLBACK_STATUS is only triggered if the status changed since the last triggering.

Definition at line 143 of file bricklet_gps.h.

#define GPS_DEVICE_IDENTIFIER 222

This constant is used to identify a GPS Bricklet.

The gps_get_identity function and the IPCON_CALLBACK_ENUMERATE callback of the IP Connection have a device_identifier parameter to specify the Brick's or Bricklet's type.

Definition at line 234 of file bricklet_gps.h.

#define GPS_FIX_2D_FIX 2

Definition at line 198 of file bricklet_gps.h.

#define GPS_FIX_3D_FIX 3

Definition at line 203 of file bricklet_gps.h.

#define GPS_FIX_NO_FIX 1

Definition at line 193 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_ALTITUDE 3

Definition at line 44 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_ALTITUDE_CALLBACK_PERIOD 12

Definition at line 89 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_COORDINATES 1

Definition at line 34 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_COORDINATES_CALLBACK_PERIOD 8

Definition at line 69 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_DATE_TIME 5

Definition at line 54 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_DATE_TIME_CALLBACK_PERIOD 16

Definition at line 109 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_IDENTITY 255

Definition at line 114 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_MOTION 4

Definition at line 49 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_MOTION_CALLBACK_PERIOD 14

Definition at line 99 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_STATUS 2

Definition at line 39 of file bricklet_gps.h.

#define GPS_FUNCTION_GET_STATUS_CALLBACK_PERIOD 10

Definition at line 79 of file bricklet_gps.h.

#define GPS_FUNCTION_RESTART 6

Definition at line 59 of file bricklet_gps.h.

#define GPS_FUNCTION_SET_ALTITUDE_CALLBACK_PERIOD 11

Definition at line 84 of file bricklet_gps.h.

#define GPS_FUNCTION_SET_COORDINATES_CALLBACK_PERIOD 7

Definition at line 64 of file bricklet_gps.h.

#define GPS_FUNCTION_SET_DATE_TIME_CALLBACK_PERIOD 15

Definition at line 104 of file bricklet_gps.h.

#define GPS_FUNCTION_SET_MOTION_CALLBACK_PERIOD 13

Definition at line 94 of file bricklet_gps.h.

#define GPS_FUNCTION_SET_STATUS_CALLBACK_PERIOD 9

Definition at line 74 of file bricklet_gps.h.

#define GPS_RESTART_TYPE_COLD_START 2

Definition at line 218 of file bricklet_gps.h.

#define GPS_RESTART_TYPE_FACTORY_RESET 3

Definition at line 223 of file bricklet_gps.h.

#define GPS_RESTART_TYPE_HOT_START 0

Definition at line 208 of file bricklet_gps.h.

#define GPS_RESTART_TYPE_WARM_START 1

Definition at line 213 of file bricklet_gps.h.

Typedef Documentation

typedef Device GPS

Device for receiving GPS position

Definition at line 29 of file bricklet_gps.h.

Function Documentation

void gps_create	(	GPS *	gps,
		const char *	uid,
		IPConnection *	ipcon
	)

Creates the device object gps with the unique device ID uid and adds it to the IPConnection ipcon.

Definition at line 319 of file bricklet_gps.c.

void gps_destroy ( GPS * gps )

Removes the device object gps from its IPConnection and destroys it. The device object cannot be used anymore afterwards.

Definition at line 356 of file bricklet_gps.c.

int gps_get_altitude	(	GPS *	gps,
		uint32_t *	ret_altitude,
		uint32_t *	ret_geoidal_separation
	)

Returns the current altitude and corresponding geoidal separation.

Both values are given in cm.

This data is only valid if there is currently a fix as indicated by gps_get_status.

Definition at line 439 of file bricklet_gps.c.

int gps_get_altitude_callback_period	(	GPS *	gps,
		uint32_t *	ret_period
	)

Returns the period as set by gps_set_altitude_callback_period.

Definition at line 643 of file bricklet_gps.c.

int gps_get_api_version	(	GPS *	gps,
		uint8_t	ret_api_version[3]
	)

Returns the API version (major, minor, release) of the bindings for this device.

Definition at line 376 of file bricklet_gps.c.

int gps_get_coordinates	(	GPS *	gps,
		uint32_t *	ret_latitude,
		char *	ret_ns,
		uint32_t *	ret_longitude,
		char *	ret_ew,
		uint16_t *	ret_pdop,
		uint16_t *	ret_hdop,
		uint16_t *	ret_vdop,
		uint16_t *	ret_epe
	)

Returns the GPS coordinates. Latitude and longitude are given in the ``DD.dddddd°`` format, the value 57123468 means 57.123468°. The parameter ``ns`` and ``ew`` are the cardinal directions for latitude and longitude. Possible values for ``ns`` and ``ew`` are 'N', 'S', 'E' and 'W' (north, south, east and west).

PDOP, HDOP and VDOP are the dilution of precision (DOP) values. They specify the additional multiplicative effect of GPS satellite geometry on GPS precision. See `here <http://en.wikipedia.org/wiki/Dilution_of_precision_(GPS)>`__ for more information. The values are give in hundredths.

EPE is the "Estimated Position Error". The EPE is given in cm. This is not the absolute maximum error, it is the error with a specific confidence. See `here <http://www.nps.gov/gis/gps/WhatisEPE.html>`__ for more information.

This data is only valid if there is currently a fix as indicated by gps_get_status.

Definition at line 380 of file bricklet_gps.c.

int gps_get_coordinates_callback_period	(	GPS *	gps,
		uint32_t *	ret_period
	)

Returns the period as set by gps_set_coordinates_callback_period.

Definition at line 555 of file bricklet_gps.c.

int gps_get_date_time	(	GPS *	gps,
		uint32_t *	ret_date,
		uint32_t *	ret_time
	)

Returns the current date and time. The date is given in the format ``ddmmyy`` and the time is given in the format ``hhmmss.sss``. For example, 140713 means 14.05.13 as date and 195923568 means 19:59:23.568 as time.

Definition at line 491 of file bricklet_gps.c.

int gps_get_date_time_callback_period	(	GPS *	gps,
		uint32_t *	ret_period
	)

Returns the period as set by gps_set_date_time_callback_period.

Definition at line 731 of file bricklet_gps.c.

int gps_get_identity	(	GPS *	gps,
		char	ret_uid[8],
		char	ret_connected_uid[8],
		char *	ret_position,
		uint8_t	ret_hardware_version[3],
		uint8_t	ret_firmware_version[3],
		uint16_t *	ret_device_identifier
	)

Returns the UID, the UID where the Bricklet is connected to, the position, the hardware and firmware version as well as the device identifier.

The position can be 'a', 'b', 'c' or 'd'.

The device identifier numbers can be found :ref:`here <device_identifier>`. |device_identifier_constant|

Definition at line 756 of file bricklet_gps.c.

int gps_get_motion	(	GPS *	gps,
		uint32_t *	ret_course,
		uint32_t *	ret_speed
	)

Returns the current course and speed. Course is given in hundredths degree and speed is given in hundredths km/h. A course of 0° means the Bricklet is traveling north bound and 90° means it is traveling east bound.

Please note that this only returns useful values if an actual movement is present.

This data is only valid if there is currently a fix as indicated by gps_get_status.

Definition at line 465 of file bricklet_gps.c.

int gps_get_motion_callback_period	(	GPS *	gps,
		uint32_t *	ret_period
	)

Returns the period as set by gps_set_motion_callback_period.

Definition at line 687 of file bricklet_gps.c.

int gps_get_response_expected	(	GPS *	gps,
		uint8_t	function_id,
		bool *	ret_response_expected
	)

Returns the response expected flag for the function specified by the function_id parameter. It is *true* if the function is expected to send a response, *false* otherwise.

For getter functions this is enabled by default and cannot be disabled, because those functions will always send a response. For callback configuration functions it is enabled by default too, but can be disabled via the gps_set_response_expected function. For setter functions it is disabled by default and can be enabled.

Enabling the response expected flag for a setter function allows to detect timeouts and other error conditions calls of this setter as well. The device will then send a response for this purpose. If this flag is disabled for a setter function then no response is send and errors are silently ignored, because they cannot be detected.

Definition at line 360 of file bricklet_gps.c.

int gps_get_status	(	GPS *	gps,
		uint8_t *	ret_fix,
		uint8_t *	ret_satellites_view,
		uint8_t *	ret_satellites_used
	)

Returns the current fix status, the number of satellites that are in view and the number of satellites that are currently used.

Possible fix status values can be:

 *  "Value", "Description"
 * 
 *  "1", "No Fix, {@link gps_get_coordinates} and {@link gps_get_altitude} return invalid data"
 *  "2", "2D Fix, only {@link gps_get_coordinates} returns valid data"
 *  "3", "3D Fix, {@link gps_get_coordinates} and {@link gps_get_altitude} return valid data"
 *

There is also a :ref:`blue LED <gps_bricklet_fix_led>` on the Bricklet that indicates the fix status.

Definition at line 412 of file bricklet_gps.c.

int gps_get_status_callback_period	(	GPS *	gps,
		uint32_t *	ret_period
	)

Returns the period as set by gps_set_status_callback_period.

Definition at line 599 of file bricklet_gps.c.

void gps_register_callback	(	GPS *	gps,
		uint8_t	id,
		void *	callback,
		void *	user_data
	)

Registers a callback with ID id to the function callback. The user_data will be given as a parameter of the callback.

Definition at line 372 of file bricklet_gps.c.

int gps_restart	(	GPS *	gps,
		uint8_t	restart_type
	)

Restarts the GPS Bricklet, the following restart types are available:

 *  "Value", "Description"
 * 
 *  "0", "Hot start (use all available data in the NV store)"
 *  "1", "Warm start (don't use ephemeris at restart)"
 *  "2", "Cold start (don't use time, position, almanacs and ephemeris at restart)"
 *  "3", "Factory reset (clear all system/user configurations at restart)"
 *

Definition at line 517 of file bricklet_gps.c.

int gps_set_altitude_callback_period	(	GPS *	gps,
		uint32_t	period
	)

Sets the period in ms with which the GPS_CALLBACK_ALTITUDE callback is triggered periodically. A value of 0 turns the callback off.

GPS_CALLBACK_ALTITUDE is only triggered if the altitude changed since the last triggering.

The default value is 0.

Definition at line 624 of file bricklet_gps.c.

int gps_set_coordinates_callback_period	(	GPS *	gps,
		uint32_t	period
	)

Sets the period in ms with which the GPS_CALLBACK_COORDINATES callback is triggered periodically. A value of 0 turns the callback off.

GPS_CALLBACK_COORDINATES is only triggered if the coordinates changed since the last triggering.

The default value is 0.

Definition at line 536 of file bricklet_gps.c.

int gps_set_date_time_callback_period	(	GPS *	gps,
		uint32_t	period
	)

Sets the period in ms with which the GPS_CALLBACK_DATE_TIME callback is triggered periodically. A value of 0 turns the callback off.

GPS_CALLBACK_DATE_TIME is only triggered if the date or time changed since the last triggering.

The default value is 0.

Definition at line 712 of file bricklet_gps.c.

int gps_set_motion_callback_period	(	GPS *	gps,
		uint32_t	period
	)

Sets the period in ms with which the GPS_CALLBACK_MOTION callback is triggered periodically. A value of 0 turns the callback off.

GPS_CALLBACK_MOTION is only triggered if the motion changed since the last triggering.

The default value is 0.

Definition at line 668 of file bricklet_gps.c.

int gps_set_response_expected	(	GPS *	gps,
		uint8_t	function_id,
		bool	response_expected
	)

Changes the response expected flag of the function specified by the function_id parameter. This flag can only be changed for setter (default value: *false*) and callback configuration functions (default value: *true*). For getter functions it is always enabled and callbacks it is always disabled.

Enabling the response expected flag for a setter function allows to detect timeouts and other error conditions calls of this setter as well. The device will then send a response for this purpose. If this flag is disabled for a setter function then no response is send and errors are silently ignored, because they cannot be detected.

Definition at line 364 of file bricklet_gps.c.

int gps_set_response_expected_all	(	GPS *	gps,
		bool	response_expected
	)

Changes the response expected flag for all setter and callback configuration functions of this device at once.

Definition at line 368 of file bricklet_gps.c.

int gps_set_status_callback_period	(	GPS *	gps,
		uint32_t	period
	)

Sets the period in ms with which the GPS_CALLBACK_STATUS callback is triggered periodically. A value of 0 turns the callback off.

GPS_CALLBACK_STATUS is only triggered if the status changed since the last triggering.

The default value is 0.

Definition at line 580 of file bricklet_gps.c.

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation