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 |
|