| 1 |
NAME |
| 2 |
AnyEvent::GPSD - event based interface to GPSD |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use AnyEvent::GPSD; |
| 6 |
|
| 7 |
DESCRIPTION |
| 8 |
This module is an AnyEvent user, you need to make sure that you use and |
| 9 |
run a supported event loop. |
| 10 |
|
| 11 |
This module implements an interface to GPSD (http://gpsd.berlios.de/). |
| 12 |
|
| 13 |
You need to consult the GPSD protocol desription in the manpage to make |
| 14 |
better sense of this module. |
| 15 |
|
| 16 |
METHODS |
| 17 |
$gps = new AnyEvent::GPSD [key => value...] |
| 18 |
Creates a (virtual) connection to the GPSD. If the "hostname:port" |
| 19 |
argument is missing then "localhost:2947" will be used. |
| 20 |
|
| 21 |
If the connection cannot be established, then it will retry every |
| 22 |
second. Otherwise, the connection is put into watcher mode. |
| 23 |
|
| 24 |
You can specify various configuration parameters, most of them |
| 25 |
callbacks: |
| 26 |
|
| 27 |
host => $hostname |
| 28 |
The host to connect to, default is "locahost". |
| 29 |
|
| 30 |
port => $port |
| 31 |
The port to connect to, default is 2947. |
| 32 |
|
| 33 |
min_speed => $speed_in_m_per_s |
| 34 |
Sets the mininum speed (default: 0) that is considered real for |
| 35 |
the purposes of replay compression or estimate. Speeds below |
| 36 |
this value will be considered 0. |
| 37 |
|
| 38 |
on_error => $cb->($gps) |
| 39 |
Called on every connection or protocol failure, reason is in $! |
| 40 |
(protocl errors are signalled via EBADMSG). Can be used to bail |
| 41 |
out if you are not interested in retries. |
| 42 |
|
| 43 |
on_connect => $cb->($gps) |
| 44 |
Nornormally used: Called on every successful connection |
| 45 |
establish. |
| 46 |
|
| 47 |
on_response => $cb->($gps, $type, $data, $time) |
| 48 |
Not normally used: Called on every response received from GPSD. |
| 49 |
$type is the single letter type and $data is the data portion, |
| 50 |
if any. $time is the timestamp that this message was received |
| 51 |
at. |
| 52 |
|
| 53 |
on_satellite_info => $cb->($gps, {satellite-info}...) |
| 54 |
Called each time the satellite info changes, also on first |
| 55 |
connect. Each "satellite-info" hash contains at least the |
| 56 |
following members (mnemonic: all keys have three letters): |
| 57 |
|
| 58 |
"prn" holds the satellite PRN (1..32 GPS, anything higher is |
| 59 |
wASS/EGNOS/MCAS etc, see GPS::PRN). |
| 60 |
|
| 61 |
"ele", "azi" contain the elevation (0..90) and azimuth (0..359) |
| 62 |
of the satellite. |
| 63 |
|
| 64 |
"snr" contains the signal strength in decibals (28+ is usually |
| 65 |
the minimum value for a good fix). |
| 66 |
|
| 67 |
"fix" contains either 1 to indicate that this satellite was used |
| 68 |
for the last position fix, 0 otherwise. EGNOS/WAAS etc. |
| 69 |
satellites will always show as 0, even if their correction info |
| 70 |
was used. |
| 71 |
|
| 72 |
The passed hash references are read-only. |
| 73 |
|
| 74 |
on_fix => $cb->({point}) |
| 75 |
Called regularly (usually about once/second), even when there is |
| 76 |
no connection to the GPSD (so is useful to update your idea of |
| 77 |
the current position). The passed hash reference must *not* be |
| 78 |
modified in any way. |
| 79 |
|
| 80 |
If "mode" is 2 or 3, then the "{point}" hash contains at least |
| 81 |
the following members, otherwise it is undefined which members |
| 82 |
exist. Members whose values are not known are "undef" (usually |
| 83 |
the error values, speed and so on). |
| 84 |
|
| 85 |
time when this fix was received (s) |
| 86 |
|
| 87 |
lat latitude (S -90..90 N) |
| 88 |
lon longitude (W -180..180 E) |
| 89 |
alt altitude |
| 90 |
|
| 91 |
herr estimated horizontal error (m) |
| 92 |
verr estimated vertical error (m) |
| 93 |
|
| 94 |
bearing bearing over ground (0..360) |
| 95 |
berr estimated error in bearing (degrees) |
| 96 |
speed speed over ground (m/s) |
| 97 |
serr estimated error in speed over ground (m/s) |
| 98 |
vspeed vertical velocity, positive = upwards (m/s) |
| 99 |
vserr estimated error in vspeed (m/s) |
| 100 |
|
| 101 |
mode 1 = no fix, 2 = 2d fix, 3 = 3d fix |
| 102 |
|
| 103 |
($lat, $lon) = $gps->estimate ([$max_seconds]) |
| 104 |
This returns an estimate of the current position based on the last |
| 105 |
fix and the time passed since then. |
| 106 |
|
| 107 |
Useful for interactive applications where you want more frequent |
| 108 |
updates, but not very useful to store, as the next fix might well be |
| 109 |
totally off. For example, when displaying a real-time map, you could |
| 110 |
simply call "estimate" ten times a second and update the cursor or |
| 111 |
map position, but you should use "on_fix" to actually gather data to |
| 112 |
plot the course itself. |
| 113 |
|
| 114 |
If the fix is older then $max_seconds (default: 1.9 times the update |
| 115 |
interval, i.e. usually 1.9 seconds) or if no fix is available, |
| 116 |
returns the empty list. |
| 117 |
|
| 118 |
$gps->record_log ($path) |
| 119 |
If $path is defined, then that file will be created or truncated and |
| 120 |
a log of all (raw) packets received will be written to it. This log |
| 121 |
file can later be replayed by calling "$gps->replay_log ($path)". |
| 122 |
|
| 123 |
If $path is undefined then the log will be closed. |
| 124 |
|
| 125 |
$gps->replay_log ($path, %options) |
| 126 |
Replays a log file written using "record_log" (or stops replaying |
| 127 |
when $path is undefined). While the log file replays, real GPS |
| 128 |
events will be ignored. This comes in handy when testing. |
| 129 |
|
| 130 |
Please note that replaying a log will change configuration options |
| 131 |
that will not be restored, so it's best not to reuse a gpsd object |
| 132 |
after a replay. |
| 133 |
|
| 134 |
The "AnyEvent::GPSD" distribution comes with an example log |
| 135 |
(eg/example.aegps) that you can replay for testing or enjoyment |
| 136 |
purposes. |
| 137 |
|
| 138 |
The options include: |
| 139 |
|
| 140 |
compress => 1 |
| 141 |
If set to a true value (default: false), then passages without |
| 142 |
fix will be replayed much faster than passages with fix. The |
| 143 |
same happens for passages without much movement. |
| 144 |
|
| 145 |
stretch => $factor |
| 146 |
Multiplies all times by the given factor. Values < 1 make the |
| 147 |
log replay faster, values > 1 slower. Note that the frequency of |
| 148 |
fixes will not be increased, o stretch factors > 1 do not work |
| 149 |
well. |
| 150 |
|
| 151 |
A stretch factor of zero is not allowed, but if you want to |
| 152 |
replay a log instantly you may speicfy a very low value (e.g. |
| 153 |
1e-10). |
| 154 |
|
| 155 |
SEE ALSO |
| 156 |
AnyEvent. |
| 157 |
|
| 158 |
AUTHOR |
| 159 |
Marc Lehmann <schmorp@schmorp.de> |
| 160 |
http://home.schmorp.de/ |
| 161 |
|
