NAME AnyEvent::GPSD - event based interface to GPSD SYNOPSIS use AnyEvent::GPSD; DESCRIPTION This module is an AnyEvent user, you need to make sure that you use and run a supported event loop. This module implements an interface to GPSD (http://gpsd.berlios.de/). You need to consult the GPSD protocol desription in the manpage to make better sense of this module. METHODS $gps = new AnyEvent::GPSD [key => value...] Creates a (virtual) connection to the GPSD. If the "hostname:port" argument is missing then "localhost:2947" will be used. If the connection cannot be established, then it will retry every second. Otherwise, the connection is put into watcher mode. You can specify various configuration parameters, most of them callbacks: host => $hostname The host to connect to, default is "locahost". port => $port The port to connect to, default is 2947. min_speed => $speed_in_m_per_s Sets the mininum speed (default: 0) that is considered real for the purposes of replay compression or estimate. Speeds below this value will be considered 0. on_error => $cb->($gps) Called on every connection or protocol failure, reason is in $! (protocl errors are signalled via EBADMSG). Can be used to bail out if you are not interested in retries. on_connect => $cb->($gps) Nornormally used: Called on every successful connection establish. on_response => $cb->($gps, $type, $data, $time) Not normally used: Called on every response received from GPSD. $type is the single letter type and $data is the data portion, if any. $time is the timestamp that this message was received at. on_satellite_info => $cb->($gps, {satellite-info}...) Called each time the satellite info changes, also on first connect. Each "satellite-info" hash contains at least the following members (mnemonic: all keys have three letters): "prn" holds the satellite PRN (1..32 GPS, anything higher is wASS/EGNOS/MCAS etc, see GPS::PRN). "ele", "azi" contain the elevation (0..90) and azimuth (0..359) of the satellite. "snr" contains the signal strength in decibals (28+ is usually the minimum value for a good fix). "fix" contains either 1 to indicate that this satellite was used for the last position fix, 0 otherwise. EGNOS/WAAS etc. satellites will always show as 0, even if their correction info was used. The passed hash references are read-only. on_fix => $cb->({point}) Called regularly (usually about once/second), even when there is no connection to the GPSD (so is useful to update your idea of the current position). The passed hash reference must *not* be modified in any way. If "mode" is 2 or 3, then the "{point}" hash contains at least the following members, otherwise it is undefined which members exist. Members whose values are not known are "undef" (usually the error values, speed and so on). time when this fix was received (s) lat latitude (S -90..90 N) lon longitude (W -180..180 E) alt altitude herr estimated horizontal error (m) verr estimated vertical error (m) bearing bearing over ground (0..360) berr estimated error in bearing (degrees) speed speed over ground (m/s) serr estimated error in speed over ground (m/s) vspeed vertical velocity, positive = upwards (m/s) vserr estimated error in vspeed (m/s) mode 1 = no fix, 2 = 2d fix, 3 = 3d fix ($lat, $lon) = $gps->estimate ([$max_seconds]) This returns an estimate of the current position based on the last fix and the time passed since then. Useful for interactive applications where you want more frequent updates, but not very useful to store, as the next fix might well be totally off. For example, when displaying a real-time map, you could simply call "estimate" ten times a second and update the cursor or map position, but you should use "on_fix" to actually gather data to plot the course itself. If the fix is older then $max_seconds (default: 1.9 times the update interval, i.e. usually 1.9 seconds) or if no fix is available, returns the empty list. $gps->record_log ($path) If $path is defined, then that file will be created or truncated and a log of all (raw) packets received will be written to it. This log file can later be replayed by calling "$gps->replay_log ($path)". If $path is undefined then the log will be closed. $gps->replay_log ($path, %options) Replays a log file written using "record_log" (or stops replaying when $path is undefined). While the log file replays, real GPS events will be ignored. This comes in handy when testing. Please note that replaying a log will change configuration options that will not be restored, so it's best not to reuse a gpsd object after a replay. The "AnyEvent::GPSD" distribution comes with an example log (eg/example.aegps) that you can replay for testing or enjoyment purposes. The options include: compress => 1 If set to a true value (default: false), then passages without fix will be replayed much faster than passages with fix. The same happens for passages without much movement. stretch => $factor Multiplies all times by the given factor. Values < 1 make the log replay faster, values > 1 slower. Note that the frequency of fixes will not be increased, o stretch factors > 1 do not work well. A stretch factor of zero is not allowed, but if you want to replay a log instantly you may speicfy a very low value (e.g. 1e-10). SEE ALSO AnyEvent. AUTHOR Marc Lehmann http://home.schmorp.de/